What causes "concat filter requires an array argument" in Shopify/liquid?

Pass an array as the argument: {% assign b = a | concat: other_array %}

Shopify/liquid · error · Liquid::ArgumentError

concat filter requires an array argument

Error message

concat filter requires an array argument

What it means

The concat Liquid filter requires its filter argument to be an array (anything responding to to_ary). If the second argument is a scalar, string, hash, or nil, it raises Liquid::ArgumentError telling you concat needs an array argument.

Solutions

Pass an array as the argument: {% assign b = a | concat: other_array %}
Split strings into arrays first if you intended string joining (use append or split)
Verify the argument variable is defined as an array before the concat filter

Example fix

<!-- before -->
{{ tags | concat: 'sale' }}
<!-- after -->
{% assign extra = 'sale' | split: ',' %}
{{ tags | concat: extra }}

Defensive patterns

Strategy: type-guard

Validate before calling

{% unless extra %}{% assign extra = '' | split: ',' %}{% endunless %}

Type guard

def array_arg?(v)
  v.respond_to?(:to_ary)
end

Try / catch

begin
  output = Liquid::Template.parse(tpl).render(assigns)
rescue Liquid::ArgumentError => e
  raise unless e.message.include?('concat filter')
  # log and render without the concatenation
end

Prevention

Remember concat merges arrays, not strings
Default undefined variables to arrays via split: ''
Validate data shapes from metafields before templating

When it happens

Trigger: Calling {{ a | concat: 'str' }}, {{ a | concat: 5 }}, or {{ a | concat: some_hash }} where the filter argument isn't an array, or the variable is undefined/nil.

Common situations: Assuming concat joins strings (it merges arrays); passing a variable that was never assign'd; passing a hash or scalar from shop/metafield data; typos so the array variable is nil.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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

Appendix: source

Thrown at lib/liquid/standardfilters.rb:706

      input = Utils.to_s(input)
      string = Utils.to_s(string)
      input + string
    end

    # @liquid_public_docs
    # @liquid_type filter
    # @liquid_category array
    # @liquid_summary
    #   Concatenates (combines) two arrays.
    # @liquid_description
    #   > Note:
    #   > The `concat` filter won't filter out duplicates. If you want to remove duplicates, then you need to use the
    #   > [`uniq` filter](/docs/api/liquid/filters/uniq).
    # @liquid_syntax array | concat: array
    # @liquid_return [array[untyped]]
    def concat(input, array)
      unless array.respond_to?(:to_ary)
        raise ArgumentError, "concat filter requires an array argument"
      end
      InputIterator.new(input, context).concat(array)
    end

    # @liquid_public_docs
    # @liquid_type filter
    # @liquid_category string
    # @liquid_summary
    #   Adds a given string to the beginning of a string.
    # @liquid_syntax string | prepend: string
    # @liquid_return [string]
    def prepend(input, string)
      input = Utils.to_s(input)
      string = Utils.to_s(string)
      string + input
    end

    # @liquid_public_docs

View on GitHub (pinned to 807d45a6b3)