{"record":{"id":"32a2cb5e94d099c2","repo":"Shopify/liquid","slug":"errors-syntax-unknown-tag-locale-unknown-tag-t-32a2cb","errorCode":null,"errorMessage":"errors.syntax.unknown_tag (locale: 'Unknown tag 'tag'')","messagePattern":"errors\\.syntax\\.unknown_tag \\(locale: 'Unknown tag 'tag''\\)","errorType":"exception","errorClass":"Liquid::SyntaxError","httpStatus":null,"severity":"error","filePath":"lib/liquid/document.rb","lineNumber":36,"sourceCode":"    def nodelist\n      @body.nodelist\n    end\n\n    def parse(tokenizer, parse_context)\n      while parse_body(tokenizer)\n      end\n      @body.freeze\n    rescue SyntaxError => e\n      e.line_number ||= parse_context.line_number\n      raise\n    end\n\n    def unknown_tag(tag, _markup, _tokenizer)\n      case tag\n      when 'else', 'end'\n        raise SyntaxError, parse_context.locale.t(\"errors.syntax.unexpected_outer_tag\", tag: tag)\n      else\n        raise SyntaxError, parse_context.locale.t(\"errors.syntax.unknown_tag\", tag: tag)\n      end\n    end\n\n    def render_to_output_buffer(context, output)\n      @body.render_to_output_buffer(context, output)\n    end\n\n    def render(context)\n      render_to_output_buffer(context, +'')\n    end\n\n    private\n\n    def new_body\n      parse_context.new_block_body\n    end\n\n    def parse_body(tokenizer)","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/Shopify/liquid/blob/807d45a6b3d4568e64e86b375e3702df2c7c860c/lib/liquid/document.rb#L18-L54","documentation":"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.","triggerScenarios":"Template.parse encounters {% sometag %} where 'sometag' is not a built-in Liquid tag and was never registered via Liquid::Template.register_tag.","commonSituations":"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.","solutions":["Fix the tag name to a valid Liquid tag (if, unless, case, for, include, assign, capture, etc.).","Register the custom tag if you intend it: Liquid::Template.register_tag('sometag', MyTag).","Require the gem that provides the missing tag (e.g. Jekyll plugins) before parsing.","Strip or escape invalid {% %} sequences if the content is meant to be literal text."],"exampleFix":"// before\n{% ifset product.feature %}...{% endifset %}\n// after\n{% if product.feature %}...{% endif %}","handlingStrategy":"validation","validationCode":"LIQUID_TAGS = %w[if unless case for include render assign capture comment raw cycle tablerow ifchanged].freeze\ndef only_known_tags?(src)\n  src.scan(/\\{%-?\\s*(\\w+)/).flatten.all? { |t| LIQUID_TAGS.include?(t) }\nend","typeGuard":"def parseable_template?(src)\n  Liquid::Template.parse(src)\n  true\nrescue Liquid::SyntaxError => e\n  warn e.message\n  false\nend","tryCatchPattern":"begin\n  Liquid::Template.parse(src)\nrescue Liquid::SyntaxError => e\n  tag = e.message[/Unknown tag '(\\w+)'/, 1]\n  raise \"Template uses unregistered tag: #{tag}\"\nend","preventionTips":["Register all custom tags at boot, before any parse.","Require tag-providing gems explicitly in the Gemfile.","Lint templates against your tag whitelist in CI.","Document available tags for template authors."],"tags":["ruby","liquid","template-syntax","unknown-tag"],"backgroundTag":"invalid-enum-value","analyzedSha":"807d45a6b3d4568e64e86b375e3702df2c7c860c","analyzedAt":"2026-09-08T11:31:38.917Z","contentChangedAt":"2026-09-08T11:31:38.917Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}