mongodb/mongoid · error · ArgumentError

Full shard_key syntax requires 1 or 2 arguments

Error message

Full shard_key syntax requires 1 or 2 arguments

What it means

Raised by Document.shard_key when the full syntax is used with more or fewer than the supported argument count. After a leading Hash of shard key fields, Mongoid accepts at most an options Hash (one argument) or a tag array (two arguments); any other arity is rejected as an ArgumentError.

Solutions

1. Call shard_key with exactly the spec Hash plus at most one options Hash: shard_key({ a: 1, b: 1 }, { validate: false })
2. Use the shorthand field-list form for simple keys

When it happens

Trigger: Thrown at lib/mongoid/shardable.rb:129 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of mongodb/mongoid@0da0e23d71 (2026-08-23). Data as JSON: /api/errors/c476708000732bf9. Report an issue: GitHub.

Appendix: source

Thrown at lib/mongoid/shardable.rb:129

      #     include Mongoid::Document
      #     field :first_name, :type => String
      #     field :last_name, :type => String
      #
      #     shard_key first_name: 1, last_name: 1
      #   end
      def shard_key(*args)
        unless args.first.is_a?(Hash)
          # Shorthand syntax
          raise ArgumentError, 'Shorthand shard_key syntax does not permit options' if args.last.is_a?(Hash)

          spec = Hash[args.map do |name|
            [ name, 1 ]
          end]

          return shard_key(spec)
        end

        raise ArgumentError, 'Full shard_key syntax requires 1 or 2 arguments' if args.length > 2

        spec, options = args

        spec = Hash[spec.map do |name, value|
          value = value.to_s if value.is_a?(Symbol)
          [ database_field_name(name).to_sym, value ]
        end]

        self.shard_key_fields = spec.keys
        self.shard_config = {
          key: spec.freeze,
          options: (options || {}).dup.freeze
        }.freeze
      end
    end
  end
end

View on GitHub (pinned to 0da0e23d71)