What causes "options[:locale].t("errors.argument.include")" in Shopify/liquid?

Ensure the expression resolves to a String: assign a string first, e.g. {% assign name = product.template_name %}{% include name %}

Shopify/liquid · error · ArgumentError

errors.argument.include

errors.argument.include

Error message

options[:locale].t("errors.argument.include")

What it means

Include#render_to_output_buffer raises ArgumentError when the evaluated template name expression is not a String at render time. Unlike the syntax errors this occurs during rendering, meaning the {% include %} tag parsed fine but resolved to a non-string (nil, Integer, Array, etc.).

Solutions

Ensure the expression resolves to a String: assign a string first, e.g. {% assign name = product.template_name %}{% include name %}
Guard with {% if some_var %}{% include some_var %}{% endif %} or provide a default via the assign/filter
If using a numeric key, convert to a string in the assigned value

Example fix

// before
{% include product.id %}
// after
{% assign partial = product.slug %}
{% if partial %}{% include partial %}{% endif %}

Defensive patterns

Strategy: type-guard

Validate before calling

name = context.evaluate(template_name_expr)
raise ArgumentError, 'include name must be a String' unless name.is_a?(String) && !name.empty?

Type guard

def string_partial_name?(value)
  value.is_a?(String) && !value.empty?
end

Try / catch

begin
  output = template.render(assigns)
rescue Liquid::ArgumentError => e
  if e.message.include?('errors.argument.include')
    logger.warn("include resolved to non-string: #{e.message}")
    ''
  else
    raise
  end
end

Prevention

Assign include names to variables first and ensure they are strings
Guard dynamic includes with {% if %} checks so nil names never render
Avoid including numeric IDs; convert to slug/string names upstream

When it happens

Trigger: {% include some_var %} where some_var evaluates to nil or a non-string (e.g. a number from a drop or assign); {% include product.id %} where id is an integer; a variable that was never assigned so it evaluates to nil.

Common situations: Dynamically choosing partials from variables that may be unassigned; passing numeric IDs as include names; Shopify/Liquid templates with optional variables that are empty at render time.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at lib/liquid/tags/include.rb:39

    prepend Tag::Disableable

    FOR = 'for'
    SYNTAX = /(#{QuotedFragment}+)(\s+(with|#{FOR})\s+(#{QuotedFragment}+))?(\s+(?:as)\s+(#{VariableSegment}+))?/o
    Syntax = SYNTAX

    attr_reader :template_name_expr, :variable_name_expr, :attributes

    def initialize(tag_name, markup, options)
      super
      parse_with_selected_parser(markup)
    end

    def parse(_tokens)
    end

    def render_to_output_buffer(context, output)
      template_name = context.evaluate(@template_name_expr)
      raise ArgumentError, options[:locale].t("errors.argument.include") unless template_name.is_a?(String)

      partial = PartialCache.load(
        template_name,
        context: context,
        parse_context: parse_context,
      )

      context_variable_name = @alias_name || template_name.split('/').last

      variable = if @variable_name_expr
        context.evaluate(@variable_name_expr)
      else
        context.find_variable(template_name, raise_on_not_found: false)
      end

      old_template_name = context.template_name
      old_partial       = context.partial

View on GitHub (pinned to 807d45a6b3)