Shopify/liquid · error · Liquid::SyntaxError

errors.syntax.unknown_tag (locale: 'Unknown tag 'tag'')

Error message

errors.syntax.unknown_tag (locale: 'Unknown tag 'tag'')

What it means

Document#unknown_tag raises Liquid::SyntaxError with the localized 'errors.syntax.unknown_tag' message when the parser encounters any tag that is neither 'else'/'end' nor registered with the tag system. This is the catch-all for unrecognized {% ... %} tags at parse time.

Solutions

1. Fix the tag name to a valid Liquid tag (if, unless, case, for, include, assign, capture, etc.).
2. Register the custom tag if you intend it: Liquid::Template.register_tag('sometag', MyTag).
3. Require the gem that provides the missing tag (e.g. Jekyll plugins) before parsing.
4. Strip or escape invalid {% %} sequences if the content is meant to be literal text.

Example fix

// before
{% ifset product.feature %}...{% endifset %}
// after
{% if product.feature %}...{% endif %}

LIQUID_TAGS = %w[if unless case for include render assign capture comment raw cycle tablerow ifchanged].freeze
def only_known_tags?(src)
  src.scan(/\{%-?\s*(\w+)/).flatten.all? { |t| LIQUID_TAGS.include?(t) }
end

def parseable_template?(src)
  Liquid::Template.parse(src)
  true
rescue Liquid::SyntaxError => e
  warn e.message
  false
end

begin
  Liquid::Template.parse(src)
rescue Liquid::SyntaxError => e
  tag = e.message[/Unknown tag '(\w+)'/, 1]
  raise "Template uses unregistered tag: #{tag}"
end

When it happens

Trigger: Template.parse encounters {% sometag %} where 'sometag' is not a built-in Liquid tag and was never registered via Liquid::Template.register_tag.

Common situations: Typo in a tag name ({% ifset %} instead of {% if %}); using tags from another templating engine (e.g. Jinja or Jekyll plugins) in plain Liquid; forgetting to require/register a custom tag gem in the host app.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• errors.syntax.unknown_tag (locale: 'Unknown tag 'tag'')
• errors.syntax.unexpected_outer_tag
• errors.syntax.assign
• errors.syntax.capture
• errors.syntax.case

AI-assisted analysis of Shopify/liquid@807d45a6b3 (2026-09-08). Data as JSON: /api/errors/32a2cb5e94d099c2. Report an issue: GitHub.

Appendix: source

Thrown at lib/liquid/document.rb:36

    def nodelist
      @body.nodelist
    end

    def parse(tokenizer, parse_context)
      while parse_body(tokenizer)
      end
      @body.freeze
    rescue SyntaxError => e
      e.line_number ||= parse_context.line_number
      raise
    end

    def unknown_tag(tag, _markup, _tokenizer)
      case tag
      when 'else', 'end'
        raise SyntaxError, parse_context.locale.t("errors.syntax.unexpected_outer_tag", tag: tag)
      else
        raise SyntaxError, parse_context.locale.t("errors.syntax.unknown_tag", tag: tag)
      end
    end

    def render_to_output_buffer(context, output)
      @body.render_to_output_buffer(context, output)
    end

    def render(context)
      render_to_output_buffer(context, +'')
    end

    private

    def new_body
      parse_context.new_block_body
    end

    def parse_body(tokenizer)

View on GitHub (pinned to 807d45a6b3)