ruby-grape/grape · error · Grape::Exceptions::InvalidVersionerOption

unknown :using for versioner: %{strategy}

Error message

unknown :using for versioner: %{strategy}

What it means

`version 'v1', using: :strategy` selects the versioning middleware from a registry populated by Grape::Middleware::Versioner subclasses. Only :path, :header, :accept_version_header, and :param are registered; anything else raises Grape::Exceptions::InvalidVersionerOption ('unknown :using for versioner: X') when the API class is mounted.

Source

Thrown at lib/grape/middleware/versioner.rb:21

# Versioners set env['api.version'] when a version is defined on an API and
# on the requests. The current methods for determining version are:
#
#   :header - version from HTTP Accept header.
#   :accept_version_header - version from HTTP Accept-Version header
#   :path   - version from uri. e.g. /v1/resource
#   :param  - version from uri query string, e.g. /v1/resource?apiver=v1
# See individual classes for details.
module Grape
  module Middleware
    module Versioner
      extend Grape::Util::Registry

      module_function

      # @param strategy [Symbol] :path, :header, :accept_version_header or :param
      # @return a middleware class based on strategy
      def using(strategy)
        raise Grape::Exceptions::InvalidVersionerOption, strategy unless registry.key?(strategy)

        registry[strategy]
      end
    end
  end
end

View on GitHub (pinned to 22d7975629)

Solutions

1. Use one of the four supported symbols: :path, :header, :accept_version_header, or :param.
2. For a custom strategy, subclass Grape::Middleware::Versioner::Base (auto-registered by its demodulized, underscored name) or call Grape::Middleware::Versioner.register with your class and pass that short name.

Example fix

# before
version 'v1', using: :path_version # raises InvalidVersionerOption

# after
version 'v1', using: :path
mount MyAPI => '/api'

VERSIONERS = %i[path header accept_version_header param].freeze

raise ArgumentError, "using: must be one of #{VERSIONERS.join(', ')}" unless VERSIONERS.include?(strategy)
version 'v1', using: strategy

def valid_versioner?(sym) = %i[path header accept_version_header param].include?(sym)

When it happens

Trigger: `version 'v1', using: :path_version` or `using: :query`. Passing a string `using: 'header'`-style typo like `:headers`. A custom strategy class that was never registered via Grape::Middleware::Versioner.register.

Common situations: Typos when first adding API versioning. Copying config between apps where a custom versioner middleware existed. Renaming strategies during upgrades and missing a call site.

Related errors

• unknown params_builder: %{params_builder_type}
• `#{self.class.name}#[]` is deprecated. Use the named accesso
• Returning or throwing a Hash from a rescue handler is deprec
• type #{type} should support coercion via `[]`
• #declared is not available prior to parameter validation

AI-assisted analysis of ruby-grape/grape@22d7975629 (2026-08-21). Data as JSON: /api/errors/e9d2e898608dbb0d. Report an issue: GitHub.