Troubleshooting

When a lookup throws

Lookups are file reads, and three things make them throw rather than return an empty result:

• A missing database file. The exception comes from maxmind-db/reader itself — an \InvalidArgumentException naming the file — so that is the type to catch; there is no package-specific exception. Run php artisan geolocator:update-iplocationdb once per environment, or bake the files into your image.
• lookup() reads all three editions. It opens the country, city and ASN readers, so all three files have to exist even if you only ever read the country from the result. To depend on fewer files, call lookupCountry(), lookupCity() or lookupAsn(), which read one edition each.
• IPv6 addresses read the -IPv6 editions. lookup('2a00:1450:4009::200e') resolves through IPLOCATIONDB_*_PATH_V6, so an IPv6 address throws on a machine where only the IPv4 editions were configured — while every IPv4 address keeps working.

Private, reserved and unparseable addresses are not on that list: they are filtered before the database is queried, so they return an empty result. What an empty result does not mean is that the database is absent — when the file cannot be opened, the lookup throws even for 192.168.1.1.

Symptoms

Symptom	Cause	Fix
InvalidArgumentException naming a .mmdb file	the databases were never downloaded	php artisan geolocator:update-iplocationdb, or set IPLOCATIONDB_*_PATH
IPv6 addresses throw while IPv4 works	the -IPv6 editions are not configured	set IPLOCATIONDB_*_PATH_V6, or install them
$location->country is null but $location->city is populated	the country edition has no record for the address; each DTO is built from its own edition only	fall back to $location->city->countryCode, or call lookupCountry()
Driver [x] is not supported.	no creator is registered for that name	Geolocator::extend('x', ...) or a createXDriver() method; a container binding is not enough
Lookups serve the old database after an update	a reader opened before the update is still in use	restart that process; workers and Octane drop it on the next job or request
Fake lookups return empty results at random	chanceOfEmpty is set above 0	pass chanceOfEmpty: 0 — that is the default
A country code returns null	it is not in the bundled country list	CountryResult::create() normalises UK→GB, EL→GR, AN→CW, CS→RS; CityResult::create() does not

Still stuck

• Usage for what a lookup returns and how an empty result is meant to look.
• Configuration for the paths and the driver name.
• Database updates for what the update command reports and emits.