Shopify Liquid Error: Unknown Tag "schema" — Fixed

You added a {% schema %} block and the theme editor now throws Liquid error: Unknown tag 'schema'.

The tag is valid Liquid — but only in one place. Nine times out of ten this error means the file you put it in is not a section file. Here is how to confirm that and fix it.

Symptom

• The theme editor shows Liquid error (line N): Unknown tag 'schema' where the block starts.
• Running shopify theme check reports UnknownTag.
• The section does not appear in the "Add section" list.
• The page may still render, with the raw schema JSON printed as visible text.

Cause

Shopify only parses {% schema %} in files under sections/. Everywhere else the tag is unrecognised, because schema defines section settings and nothing else has settings to define.

The three ways people hit this:

1. The file is in snippets/. A snippet rendered with {% render %} cannot carry schema. This is the most common case — a section gets refactored into a snippet and the schema block travels with it.
2. The file is in templates/. JSON templates configure sections; they do not declare them.
3. The file is in layout/. theme.liquid has no schema.

A fourth, rarer cause: the schema block sits inside a {% capture %}, {% if %} or any other tag. Schema must be at the top level of the file, never nested.

Fix

If the code is in a snippet

Move the file to sections/ and render it as a section:

{% comment %} Before — snippets/product-highlights.liquid {% endcomment %}
{% render 'product-highlights' %}

{% comment %} After — sections/product-highlights.liquid {% endcomment %}
{% section 'product-highlights' %}

If you need it inside a JSON template instead, add it to the template's section list:

{
  "sections": {
    "highlights": {
      "type": "product-highlights",
      "settings": { "heading": "Why shop with us" }
    }
  },
  "order": ["highlights"]
}

If you need the markup in a snippet and the settings in a section

Keep the schema in the section and pass values down:

{% comment %} sections/product-highlights.liquid {% endcomment %}
{% render 'highlight-card', heading: section.settings.heading %}

{% schema %}
{
  "name": "Product highlights",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "Why shop with us" }
  ],
  "presets": [{ "name": "Product highlights" }]
}
{% endschema %}

The snippet then reads {{ heading }} — it never touches section.settings directly.

If the schema is nested

Move it out. This fails:

{% if section.settings.enabled %}
  {% schema %}{ "name": "Broken" }{% endschema %}
{% endif %}

Schema is read at compile time, not render time, so a conditional around it is meaningless.

Verify

1. Confirm the file path starts with sections/.
2. Run shopify theme check — the UnknownTag error should be gone.
3. Open the theme editor and confirm the section appears under "Add section".
4. Change a setting and confirm the value reaches the template.

Prevent

• One schema per file, at the top level. Put it at the very bottom of the section file, after all markup, by convention.
• Run shopify theme check before pushing. It catches this in a second.
• When refactoring a section into a snippet, move the schema deliberately — decide which settings stay in the parent section and pass them as render arguments.

Frequently asked questions

Can a snippet have its own settings?

No. Snippets receive values as arguments from whatever renders them. If a block of markup needs merchant-editable settings, it has to be a section (or a block within one).

Why does the page still render with the error?

Liquid fails soft. The unknown tag is skipped and its contents are output as text, so you often see raw JSON on the page rather than a blank screen.

Does this apply to {% javascript %} and {% stylesheet %} too?

Yes — both are also section-only tags and produce the same error in a snippet.

Related reading

• Section schema will not save
• Metafields not showing in Liquid
• custom Shopify sections — our service page

Need a hand?

We debug and build Shopify themes for merchants across the USA, UAE, Saudi Arabia, Qatar and the UK. If a theme is throwing errors you cannot pin down, get a free audit or read more about our Shopify theme development work.