Shopify/liquid · error · Liquid::SyntaxError

errors.syntax.block_tag_unexpected_args

errors.syntax.block_tag_unexpected_args

Error message

parse_context.locale.t("errors.syntax.block_tag_unexpected_args", tag: tag_name)

What it means

The `{% doc %}` block tag accepts no arguments. ensure_valid_markup, called from Doc#initialize, raises SyntaxError with the localized 'errors.syntax.block_tag_unexpected_args' (interpolating the tag name) when the markup does not match the NO_UNEXPECTED_ARGS pattern.

Solutions

Remove all arguments: use bare {% doc %} ... {% enddoc %}
If you need to label the doc content, put the label on a comment line inside the block
Update any template generators that append attributes to block tags
Add a lint rule rejecting arguments on argument-less block tags

Example fix

// before
{% doc description %}
  Renders the price.
{% enddoc %}
// after
{% doc %}
  description: Renders the price.
{% enddoc %}

Defensive patterns

Strategy: validation

Validate before calling

def valid_doc_markup?(markup)
  markup.strip.empty?
end

Try / catch

begin
  Liquid::Template.parse(source)
rescue Liquid::SyntaxError => e
  raise "doc tag takes no arguments: #{e.message}"
end

Prevention

Never add arguments to `{% doc %}`
Put labels inside the block content, not on the tag
Check generator tooling for injected tag attributes

When it happens

Trigger: Writing arguments on the opening doc tag, e.g. `{% doc description %} ... {% enddoc %}` or `{% doc name="x" %}`.

Common situations: Authors trying to name documentation blocks; copying doc tag usage from other documentation systems that take a title argument; tooling injecting attributes into block tags.

Related errors

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

Appendix: source

Thrown at lib/liquid/tags/doc.rb:73

    end

    def render_to_output_buffer(_context, output)
      output
    end

    def blank?
      @body.empty?
    end

    def nodelist
      [@body]
    end

    private

    def ensure_valid_markup(tag_name, markup, parse_context)
      unless NO_UNEXPECTED_ARGS.match?(markup)
        raise SyntaxError, parse_context.locale.t("errors.syntax.block_tag_unexpected_args", tag: tag_name)
      end
    end

    def raise_nested_doc_error
      raise SyntaxError, parse_context.locale.t("errors.syntax.doc_invalid_nested")
    end
  end
end

View on GitHub (pinned to 807d45a6b3)