Shopify/liquid · error · Liquid::SyntaxError

errors.syntax.tag_unexpected_args

errors.syntax.tag_unexpected_args

Error message

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

What it means

Raw#ensure_valid_markup raises SyntaxError with the tag_unexpected_args message when the {% raw %} tag's markup is non-empty. Raw takes no arguments; via Tag#parse this is enforced at initialization for any raw tag whose Syntax regex doesn't match empty markup.

Solutions

Remove everything after the tag name: use plain {% raw %} ... {% endraw %}
If you intended to escape/transform data, use filters (e.g. {{ value | json }}) or the {% literal %} construct instead of raw with arguments
Trim whitespace/stray tokens accidentally left after 'raw'

Example fix

// before
{% raw %}
// after
{% raw %}...{% endraw %}

Defensive patterns

Strategy: validation

Validate before calling

raise Liquid::SyntaxError, 'raw tag takes no arguments' unless markup.to_s.strip.empty?

Type guard

def raw_tag_valid?(markup)
  markup.to_s.strip.empty?
end

Try / catch

begin
  Liquid::Template.parse(template)
rescue Liquid::SyntaxError => e
  if e.message.include?('tag_unexpected_args')
    logger.error("Raw tag given arguments: #{e.message}")
  end
  raise
end

Prevention

{% raw %} never takes arguments — strip anything after the tag name
Use filters or {% literal %} if you need transformation, not raw parameters
Trim accidental whitespace/tokens when hand-editing raw blocks

When it happens

Trigger: {% raw something %}, {% raw data.json %}, or any {% raw %} tag containing additional text after the tag name — anywhere raw tags are parsed (strict and lax alike).

Common situations: Attempting to parameterize raw output (misunderstanding that raw is not a filter); copy-paste artifacts leaving stray characters after 'raw'; typos such as {% rawx %}-style edits that leave arguments behind.

Related errors

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

Appendix: source

Thrown at lib/liquid/tags/raw.rb:55

    def render_to_output_buffer(_context, output)
      output << @body
      output
    end

    def nodelist
      [@body]
    end

    def blank?
      @body.empty?
    end

    protected

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

View on GitHub (pinned to 807d45a6b3)