{"record":{"id":"652f0574a100e9f4","repo":"Shopify/liquid","slug":"errors-syntax-unknown-tag-locale-unknown-tag-t","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/block.rb","lineNumber":51,"sourceCode":"      Block.raise_unknown_tag(tag_name, block_name, block_delimiter, parse_context)\n    end\n\n    # @api private\n    def self.raise_unknown_tag(tag, block_name, block_delimiter, parse_context)\n      if tag == 'else'\n        raise SyntaxError, parse_context.locale.t(\n          \"errors.syntax.unexpected_else\",\n          block_name: block_name,\n        )\n      elsif tag.start_with?('end')\n        raise SyntaxError, parse_context.locale.t(\n          \"errors.syntax.invalid_delimiter\",\n          tag: tag,\n          block_name: block_name,\n          block_delimiter: block_delimiter,\n        )\n      else\n        raise SyntaxError, parse_context.locale.t(\"errors.syntax.unknown_tag\", tag: tag)\n      end\n    end\n\n    def raise_tag_never_closed(block_name)\n      raise SyntaxError, parse_context.locale.t(\"errors.syntax.tag_never_closed\", block_name: block_name)\n    end\n\n    def block_name\n      @tag_name\n    end\n\n    def block_delimiter\n      @block_delimiter ||= \"end#{block_name}\"\n    end\n\n    private\n\n    # @api public","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/Shopify/liquid/blob/807d45a6b3d4568e64e86b375e3702df2c7c860c/lib/liquid/block.rb#L33-L69","documentation":"Liquid raises this SyntaxError when the parser encounters a tag it has no registered handler for and which is neither `else` nor an `end...` delimiter. It is the catch-all unknown-tag path in Block.raise_unknown_tag, thrown at parse time with the offending tag name interpolated.","triggerScenarios":"Misspelled tag names like `{% ifx %}`; using a tag from another Liquid dialect (e.g. Shopify-only or Jekyll-only tags in plain Liquid); forgetting `require 'liquid/tag'` registration for a custom tag; tag names that don't start with 'end' but are meant as closers.","commonSituations":"Porting Shopify themes to a plain-Liquid gem; upgrading/downgrading Liquid where a tag was added or removed; custom tags defined after rendering starts or in the wrong namespace; typos in tag names.","solutions":["Fix the tag name typo, or remove the tag if it's not needed.","Register the custom tag: `Liquid::Template.register_tag('mytag', MyTag)` before parsing.","Check Liquid version docs — the tag may not exist in your version or may require an extension gem.","If it's a closer, make sure it uses the correct `end...` spelling so it routes to the delimiter check instead."],"exampleFix":"// before\nLiquid::Template.parse(\"{% prices %}...\")  # unknown tag\n// after\nclass PricesTag < Liquid::Tag; end\nLiquid::Template.register_tag('prices', PricesTag)\nLiquid::Template.parse(\"{% prices %}...\")","handlingStrategy":"validation","validationCode":"KNOWN = Liquid::Template.tags.keys\nunknown = src.scan(/{%-?\\s*(\\w+)/).flatten.uniq - KNOWN - %w[else elsif endraw]\nunknown.each { |t| puts \"unknown tag: #{t}\" }","typeGuard":"null","tryCatchPattern":"begin\n  Liquid::Template.parse(src)\nrescue Liquid::SyntaxError => e\n  if e.message.include?('Unknown tag')\n    logger.error(\"unknown liquid tag: #{e.message}\")\n    nil\n  else\n    raise\n  end\nend","preventionTips":["Register all custom tags at boot, before any parse call.","Check tag availability per Liquid version / platform (Shopify vs vanilla).","Keep a whitelist of allowed tags when accepting user templates.","Autocomplete-enabled editors reduce typos."],"tags":["liquid","template-syntax","unknown-tag","parse-error"],"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"}