Shopify/liquid · error · Liquid::ArgumentError

invalid base64 provided to base64_decode

Error message

invalid base64 provided to base64_decode

What it means

The base64_decode Liquid filter raises Liquid::ArgumentError when Base64.strict_decode64 rejects the input as invalid base64 (wrong characters, incorrect padding, or embedded whitespace/newlines forbidden by strict decoding).

Solutions

1. Validate the input matches ^[A-Za-z0-9+/]*={0,2}$ and has a length multiple of 4 before decoding
2. Use base64_url_safe_decode if the input uses - and _ characters
3. Strip whitespace/newlines from the base64 string before decoding

Example fix

<!-- before -->
{{ 'aGVsbG8
' | base64_decode }}
<!-- after -->
{{ 'aGVsbG8=' | base64_decode }}

def strict_base64?(s)
  s.is_a?(String) && s.match?(/\A[A-Za-z0-9+\/+]*={0,2}\z/) && (s.length % 4).zero?
end

def standard_base64?(v)
  v.is_a?(String) && v.match?(/\A[A-Za-z0-9+\/]+={0,2}\z/)
end

begin
  output = Liquid::Template.parse(tpl).render(assigns)
rescue Liquid::ArgumentError => e
  raise unless e.message.include?('base64_decode')
  # fall back to raw input or show placeholder
end

When it happens

Trigger: Calling {{ 'not@@base64!' | base64_decode }} with strings containing non-alphabet characters, wrong length (padding), or newlines/spaces that strict_decode64 disallows.

Common situations: Base64 strings copied with line breaks from MIME/email bodies; URL-safe base64 (- and _) fed to the strict decoder; truncated or padded-incorrectly strings from external APIs.

Related errors

• invalid base64 provided to base64_url_safe_decode
• invalid byte sequence in #
• concat filter requires an array argument
• Invalid byte sequence in #
• unsafe parse_expression cannot be used in strict2 mode

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

Appendix: source

Thrown at lib/liquid/standardfilters.rb:177

    #   Encodes a string to [Base64 format](https://developer.mozilla.org/en-US/docs/Glossary/Base64).
    # @liquid_syntax string | base64_encode
    # @liquid_return [string]
    def base64_encode(input)
      Base64.strict_encode64(Utils.to_s(input))
    end

    # @liquid_public_docs
    # @liquid_type filter
    # @liquid_category string
    # @liquid_summary
    #   Decodes a string in [Base64 format](https://developer.mozilla.org/en-US/docs/Glossary/Base64).
    # @liquid_syntax string | base64_decode
    # @liquid_return [string]
    def base64_decode(input)
      input = Utils.to_s(input)
      StandardFilters.try_coerce_encoding(Base64.strict_decode64(input), encoding: input.encoding)
    rescue ::ArgumentError
      raise Liquid::ArgumentError, "invalid base64 provided to base64_decode"
    end

    # @liquid_public_docs
    # @liquid_type filter
    # @liquid_category string
    # @liquid_summary
    #   Encodes a string to URL-safe [Base64 format](https://developer.mozilla.org/en-US/docs/Glossary/Base64).
    # @liquid_syntax string | base64_url_safe_encode
    # @liquid_return [string]
    def base64_url_safe_encode(input)
      Base64.urlsafe_encode64(Utils.to_s(input))
    end

    # @liquid_public_docs
    # @liquid_type filter
    # @liquid_category string
    # @liquid_summary
    #   Decodes a string in URL-safe [Base64 format](https://developer.mozilla.org/en-US/docs/Glossary/Base64).

View on GitHub (pinned to 807d45a6b3)