alexreisner/geocoder · error · Geocoder::ConfigurationError

The # API requires a key to be configured: #

Error message

The #{query.lookup.name} API requires a key to be configured: #{parts_string.inspect}

What it means

check_api_key_configuration! raises Geocoder::ConfigurationError before any HTTP request when the number of required API key parts for the lookup exceeds the size of the configured api_key. Multi-part key lookups need every part present.

Solutions

Configure all required key parts: Geocoder.configure(api_key: [id, code])
Check the lookup's required_api_key_parts to see how many values are needed
Sign up at the provider to obtain the missing credential
Switch to a lookup whose auth model matches the key you have

Example fix

// before
Geocoder.configure(lookup: :here, api_key: 'only_app_id')
// after
Geocoder.configure(lookup: :here, api_key: ['my_app_id', 'my_app_code'])

Defensive patterns

Strategy: validation

Validate before calling

required = Geocoder::Lookup.get(:here).required_api_key_parts
raise 'missing key parts' if required.size > Array(Geocoder.configuration.api_key).size

Try / catch

begin
  Geocoder.search(q)
rescue Geocoder::ConfigurationError => e
  raise "Geocoder API key misconfigured: #{e.message}"
end

Prevention

Configure multi-part keys as arrays matching required_api_key_parts
Check each lookup's docs for its auth requirements
Fail fast with a boot-time key configuration check

When it happens

Trigger: Using a lookup such as :here that requires an app_id + app_code (or multiple key parts) while only configuring one value in Geocoder.configure(api_key: ...), or leaving api_key nil.

Common situations: Services that changed to multi-credential auth (Here, Baidu, Google Premium), copying a single key where the provider issued an ID/secret pair.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

AI-assisted analysis of alexreisner/geocoder@c10bd70121 (2026-09-15). Data as JSON: /api/errors/48f22feae4441ec6. Report an issue: GitHub.

Appendix: source

Thrown at lib/geocoder/lookups/base.rb:333

      end

      def use_ssl?
        if supported_protocols == [:https]
          true
        elsif supported_protocols == [:http]
          false
        else
          configuration.use_https
        end
      end

      def configure_ssl!(client); end

      def check_api_key_configuration!(query)
        key_parts = query.lookup.required_api_key_parts
        if key_parts.size > Array(configuration.api_key).size
          parts_string = key_parts.size == 1 ? key_parts.first : key_parts
          raise Geocoder::ConfigurationError,
            "The #{query.lookup.name} API requires a key to be configured: " +
            parts_string.inspect
        end
      end

      ##
      # Simulate ActiveSupport's Object#to_query.
      # Removes any keys with nil value.
      #
      def hash_to_query(hash)
        require 'cgi' unless defined?(CGI) && defined?(CGI.escape)
        hash.collect{ |p|
          p[1].nil? ? nil : p.map{ |i| CGI.escape i.to_s } * '='
        }.compact.sort * '&'
      end
    end
  end
end

View on GitHub (pinned to c10bd70121)