alexreisner/geocoder · error · ConfigurationError

Please specify a valid lookup for Geocoder

Error message

Please specify a valid lookup for Geocoder (#{name.inspect} is not one of: #{valids}).

What it means

Raised by Geocoder::Lookup.spawn when Geocoder.get(name) is asked for a lookup service whose name is not in all_services. It is a generic validation guard at the factory entry point: any symbol or string (e.g. Geocoder.lookup(:foo) or Geocoder::Lookup.get(:missing)) that does not match a registered lookup class fails here before any instantiation is attempted.

Solutions

1. Use a valid lookup name (e.g. :google, :here, :nominatim, :maxmind_local)
2. Check Geocoder::Lookup.all_services for the exact list on your version
3. Require any optional lookup files needed to register the service
4. Pin/verify the Geocoder version supports the lookup you want

Example fix

// before
Geocoder.configure(lookup: :googlemaps)
// after
Geocoder.configure(lookup: :google)

raise unless Geocoder::Lookup.all_services.include?(:google)

def known_lookup?(name); Geocoder::Lookup.all_services.include?(name); end

begin
  Geocoder.search(q)
rescue Geocoder::ConfigurationError
  Geocoder.configure(lookup: :nominatim)
end

When it happens

Trigger: Geocoder.configure(lookup: :gogle) (typo), calling Geocoder.lookup(:nonexistent), or using a lookup that requires an optional gem/require that was never loaded so it is not registered.

Common situations: Typos in lookup names, forgetting to require 'geocoder/lookups/...' for less common services, or upgrading Geocoder where a lookup was renamed or removed.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Error parsing # proxy URL: '#
• Geocoder tried to log a message with an invalid log level.
• Please specify valid logger for Geocoder. Logger specified…
• region_code '# ' is invalid. use one of #…
• The # API requires a key to be configured: #

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

Appendix: source

Thrown at lib/geocoder/lookup.rb:130

    def get(name)
      @services = {} unless defined?(@services)
      @services[name] = spawn(name) unless @services.include?(name)
      @services[name]
    end


    private # -----------------------------------------------------------------

    ##
    # Spawn a Lookup of the given name.
    #
    def spawn(name)
      if all_services.include?(name)
        name = name.to_s
        instantiate_lookup(name)
      else
        valids = all_services.map(&:inspect).join(", ")
        raise ConfigurationError, "Please specify a valid lookup for Geocoder " +
          "(#{name.inspect} is not one of: #{valids})."
      end
    end

    ##
    # Convert an "underscore" version of a name into a "class" version.
    #
    def classify_name(filename)
      filename.to_s.split("_").map{ |i| i[0...1].upcase + i[1..-1] }.join
    end

    ##
    # Safely instantiate Lookup
    #
    def instantiate_lookup(name)
      class_name = classify_name(name)
      begin
        Geocoder::Lookup.const_get(class_name, inherit=false)

View on GitHub (pinned to c10bd70121)