alexreisner/geocoder · error · RuntimeError

Could not load Maxmind DB dependency. To use the GeoIP2…

Error message

Could not load Maxmind DB dependency. To use the GeoIP2 lookup you must add the #{@gem_name} gem to your Gemfile or have it installed in your system.

What it means

The GeoIP2 lookup's initializer requires the maxminddb gem (or the gem named by config :lib) when a local database :file is configured; a LoadError is re-raised as a descriptive message because the lookup cannot read the mmdb file without that dependency.

Solutions

Add gem 'maxminddb' to your Gemfile and bundle install
If using a custom DB library, set configuration[:lib] to an installed gem name
Ensure the gem is in the default (non-development) group for production deploys
Verify with `gem list maxminddb` / require 'maxminddb' in a console

Example fix

// before
# Gemfile: no maxminddb
Geocoder.configure(lookup: :geoip2, file: 'GeoLite2-City.mmdb')
// after
# Gemfile: gem 'maxminddb'
Geocoder.configure(lookup: :geoip2, file: 'GeoLite2-City.mmdb')

Defensive patterns

Strategy: validation

Validate before calling

begin; require 'maxminddb'; rescue LoadError; abort "gem 'maxminddb' required"; end

Try / catch

begin
  Geocoder.search(ip)
rescue LoadError => e
  abort "GeoIP2 dependency missing: #{e.message}"
end

Prevention

Add gem 'maxminddb' to the Gemfile
Validate DB file and lib config at boot
Include the gem in all deploy groups

When it happens

Trigger: Geocoder.configure(lookup: :geoip2, file: 'GeoLite2-City.mmdb') in a project without maxminddb in the Gemfile, or configuring :lib to a gem name that is not installed.

Common situations: Deploying to a server where the gem group containing maxminddb was excluded; typo in the :lib option; adding the lookup config but forgetting bundle install.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: source

Thrown at lib/geocoder/lookups/geoip2.rb:15

require 'geocoder/lookups/base'
require 'geocoder/results/geoip2'

module Geocoder
  module Lookup
    class Geoip2 < Base
      attr_reader :gem_name

      def initialize
        unless configuration[:file].nil?
          begin
            @gem_name = configuration[:lib] || 'maxminddb'
            require @gem_name
          rescue LoadError
            raise "Could not load Maxmind DB dependency. To use the GeoIP2 lookup you must add the #{@gem_name} gem to your Gemfile or have it installed in your system."
          end

          @mmdb = db_class.new(configuration[:file].to_s)
        end
        super
      end

      def name
        'GeoIP2'
      end

      def required_api_key_parts
        []
      end

      private

      def db_class

View on GitHub (pinned to c10bd70121)