alexreisner/geocoder · error · RuntimeError

Could not load IP2Location DB dependency. To use the…

Error message

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

What it means

The IP2LocationLite lookup's initializer requires the ip2location_ruby gem when a local database :file is configured; a LoadError is re-raised as a descriptive message because the lookup depends on that gem to read the BIN file.

Solutions

1. Add gem 'ip2location_ruby' to your Gemfile and bundle install
2. Verify installation with `gem list ip2location_ruby`
3. Ensure the gem is available in the deployment environment (not gated behind a group)
4. Alternatively switch to an HTTP-based lookup that needs no local DB gem

Example fix

// before
# Gemfile: (missing)
// after
gem 'ip2location_ruby'

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

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

When it happens

Trigger: Geocoder.configure(lookup: :ip2location_lite, file: 'IP2LOCATION-LITE-DB1.BIN') without gem 'ip2location_ruby' installed or bundled.

Common situations: New machine/CI image without the gem, forgetting bundle install after adding the lookup, gem only in a group excluded from production.

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

• Could not load geoip dependency. To use MaxMind Local…
• Could not load Maxmind DB dependency. To use the GeoIP2…
• Please install the 'json' or 'json_pure' gem to parse…
• Error parsing # proxy URL: '#
• Geocoder tried to log a message with an invalid log level.

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

Appendix: source

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

require 'geocoder/lookups/base'
require 'geocoder/results/ip2location_lite'

module Geocoder
  module Lookup
    class Ip2locationLite < Base
      attr_reader :gem_name

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

      def name
        'IP2LocationLite'
      end

      def required_api_key_parts
        []
      end

      private

      def results(query)
        return [] unless configuration[:file]

View on GitHub (pinned to c10bd70121)