alexreisner/geocoder · error · RuntimeError

Could not load geoip dependency. To use MaxMind Local…

Error message

Could not load geoip dependency. To use MaxMind Local lookup you must add the #{gem} gem to your Gemfile or have it installed in your system.

What it means

The MaxMind Local lookup requires the geoip gem (or jgeoip on JRuby) when a local :file is configured; a LoadError is re-raised as a descriptive message since it cannot read the local database without that dependency.

Solutions

Add gem 'geoip' to your Gemfile (MRI) and bundle install
On JRuby add gem 'jgeoip' instead
Check RUBY_PLATFORM in your environment to know which gem is required
Ensure the gem is in a group included in production

Example fix

// before
# Gemfile (JRuby): gem 'geoip'
// after
# Gemfile (JRuby): gem 'jgeoip'

Defensive patterns

Strategy: validation

Validate before calling

gem_name = RUBY_PLATFORM == 'java' ? 'jgeoip' : 'geoip'
begin; require gem_name; rescue LoadError; abort "#{gem_name} gem required"; end

Try / catch

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

Prevention

Bundle 'geoip' on MRI and 'jgeoip' on JRuby
Condition gem selection on platform in the Gemfile
Verify require succeeds at application boot

When it happens

Trigger: Geocoder.configure(lookup: :maxmind_local, file: 'GeoLiteCity.dat') without the geoip gem installed (MRI) or jgeoip (JRuby), detected via RUBY_PLATFORM.

Common situations: Running the app under JRuby where only the 'geoip' gem is bundled (needs jgeoip), or under MRI where only jgeoip is present; fresh deploys missing the gem.

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/eff69b1a5fb2824f. Report an issue: GitHub.

Appendix: source

Thrown at lib/geocoder/lookups/maxmind_local.rb:14

require 'ipaddr'
require 'geocoder/lookups/base'
require 'geocoder/results/maxmind_local'

module Geocoder::Lookup
  class MaxmindLocal < Base

    def initialize
      if !configuration[:file].nil?
        begin
          gem = RUBY_PLATFORM == 'java' ? 'jgeoip' : 'geoip'
          require gem
        rescue LoadError
          raise "Could not load geoip dependency. To use MaxMind Local lookup you must add the #{gem} gem to your Gemfile or have it installed in your system."
        end
      end
      super
    end

    def name
      "MaxMind Local"
    end

    def required_api_key_parts
      []
    end

    private

    def results(query)
      if configuration[:file]
        geoip_class = RUBY_PLATFORM == "java" ? JGeoIP : GeoIP

View on GitHub (pinned to c10bd70121)