bblimke/webmock · error · ArgumentError

Invalid notation. Must be one of: [:flat, :dot, :subscript,

Error message

Invalid notation. Must be one of: [:flat, :dot, :subscript, :flat_array].

What it means

WebMock::Util::QueryMapper.query_to_values parses a query string into a Hash (or array of pairs); the notation option selects how nested and repeated keys are represented, and only :flat, :dot, :subscript and :flat_array are accepted. ArgumentError is raised for any other value. The check guards direct util calls as well as internal paths that build request signatures and stub query params (add_query_params, body_as_hash, TyphoeusAdapter, etc.).

Source

Thrown at lib/webmock/util/query_mapper.rb:49

      #   WebMock::Util::QueryMapper.query_to_values("?one.two.three=four",
      #     :notation => :flat
      #   )
      #   #=> {"one.two.three" => "four"}
      #   WebMock::Util::QueryMapper(
      #     "?one[two][three][]=four&one[two][three][]=five"
      #   )
      #   #=> {"one" => {"two" => {"three" => ["four", "five"]}}}
      #   WebMock::Util::QueryMapper.query_to_values(
      #     "?one=two&one=three").query_values(:notation => :flat_array)
      #   #=> [['one', 'two'], ['one', 'three']]
      def query_to_values(query, options={})
        return nil if query.nil?
        query = query.dup.force_encoding('utf-8') if query.respond_to?(:force_encoding)

        options[:notation] ||= :subscript

        if ![:flat, :dot, :subscript, :flat_array].include?(options[:notation])
          raise ArgumentError,
                'Invalid notation. Must be one of: ' +
                '[:flat, :dot, :subscript, :flat_array].'
        end

        empty_accumulator = :flat_array == options[:notation] ? [] : {}

        query_array = collect_query_parts(query)

        query_hash = collect_query_hash(query_array, empty_accumulator, options)

        normalize_query_hash(query_hash, empty_accumulator, options)
      end

      def normalize_query_hash(query_hash, empty_accumulator, options)
        query_hash.inject(empty_accumulator.dup) do |accumulator, (key, value)|
          if options[:notation] == :flat_array
            accumulator << [key, value]
          else

View on GitHub (pinned to b187df8827)

Solutions

1. Use exactly one of the four symbols: :flat, :dot, :subscript, :flat_array (symbol, not string)
2. Map old names: array-style params (a[]=1) are :subscript; [key, value] pair lists are :flat_array; dot-notation nesting (a.b=1) is :dot
3. Avoid depending on WebMock::Util internals - parse queries yourself with Addressable::URI#query_values

Example fix

// before
values = WebMock::Util::QueryMapper.query_to_values('a=1&a=2', notation: :array)
# => ArgumentError: Invalid notation...

// after
values = WebMock::Util::QueryMapper.query_to_values('a=1&a=2', notation: :flat_array)

VALID_NOTATIONS = %i[flat dot subscript flat_array].freeze

notation = :flat_array
raise ArgumentError, "notation must be one of #{VALID_NOTATIONS}" unless VALID_NOTATIONS.include?(notation)
values = WebMock::Util::QueryMapper.query_to_values('a=1&b=2', notation: notation)

def valid_query_notation?(value)
  %i[flat dot subscript flat_array].include?(value)
end

When it happens

Trigger: Calling WebMock::Util::QueryMapper.query_to_values(query, notation: X) with X outside the whitelist: :array, :rack, :addressable, the string 'flat' instead of the symbol :flat, or an options hash where notation is set to nil before the default is applied; custom adapters or plugins layered on QueryMapper after an upgrade renamed notations.

Common situations: Code copied from webmock internals or old Stack Overflow answers using pre-2.0 notation names; upgrading webmock 1.x to 2.x (the query mapper was rewritten); pulling notation from config or ENV so it arrives as a String; gems or monkey-patches calling QueryMapper with their own notation vocabulary.

Related errors

• Key was repeated: #{key.inspect}
• #with method invoked with no arguments. Either options hash
• Wrong order. Use :before_local_stubs or :after_local_stubs
• Unknown key: #{k.inspect}. Valid keys are: #{valid_keys.map(
• Can't convert #{new_query_values.class} into Hash.

AI-assisted analysis of bblimke/webmock@b187df8827 (2026-08-23). Data as JSON: /api/errors/e26f6d09530edc58. Report an issue: GitHub.