Laravel cannot find the database host: getaddrinfo failed
SQLSTATE[HY000] [2002] php_network_getaddresses: getaddrinfo failed: Name or service not knownShort answer
The message means PHP could not turn DB_HOST into an IP address. It is a name lookup failure, not a login failure. Print the host Laravel really uses, then check three things: a stale cached config, a Docker service name used from outside Docker, and a host name that does not resolve from this machine.
Fix it fast
1Find out which cause you have
Print the host Laravel is really connecting to, after config caching and .env are applied.
php artisan config:show database.connections.mysql2Match what you see, then jump to its fix
- 1
The host printed above differs from DB_HOST in your .env.A cached config still holds the old hostFix - 2
DB_HOST=mysql (a Compose service name) while php artisan runs on the host.A Docker service name is used from outside Docker (or the other way round)Fix - 3
Same error with a real host name, such as a managed database address, and the Docker causes do not apply.The host name is misspelled or does not resolve from this machineFix
- 1
What does the error look like?
SQLSTATE[HY000] [2002] php_network_getaddresses: getaddrinfo failed: Name or service not knownSQLSTATE[HY000] [2002] php_network_getaddresses: getaddrinfo for mysql failed
Cause 1 of 3
A cached config still holds the old host
1Check
After config:cache, Laravel stops reading .env, so edits to it are ignored until the cache is rebuilt.
grep DB_HOST .env
php artisan config:show database.connections.mysql.host2Fix
Clear the cache, or rebuild it after correcting .env.
php artisan config:clear
# production: rebuild afterwards
php artisan config:cache3Verify
Run a query from the command line.
php artisan db:showConfirmed by laravel.com
Cause 2 of 3
A Docker service name is used from outside Docker (or the other way round)
1Check
Service names resolve only for containers on the Compose network. From the host you use localhost and the published port.
grep -E "DB_HOST|DB_PORT" .env
docker compose ps2Fix
Inside a container keep the service name and container port. On the host use 127.0.0.1 and the published host port (for 3307:3306 that is 3307).
# .env for commands run on the host
DB_HOST=127.0.0.1
DB_PORT=33073Verify
Connect with the same values.
php artisan db:showConfirmed by docs.docker.com
Cause 3 of 3
The host name is misspelled or does not resolve from this machine
1Check
Ask the system resolver what PHP will ask. A blank result means DNS (or /etc/hosts) cannot answer.
# use the host printed by the first step
getent hosts db.example.internal2Fix
Correct the spelling in .env, use the address the provider shows, or fix DNS on the server. Laravel also accepts a single DB_URL if your provider hands one out.
DB_HOST=db.example.internal
# or
DB_URL=mysql://user:password@db.example.internal:3306/app3Verify
Clear config and test again.
php artisan config:clear
php artisan db:showConfirmed by laravel.com
How do I stop it coming back?
- Run php artisan config:cache only in deployment, and always after you change .env.
- Keep one .env.example that shows the host for Docker and the host for a local run.
- Read the database host from config files only, never call env() in application code.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Spotless LaundryAn on-demand laundry app: Flutter on a Laravel back end, with Firebase for live updates.
- EZ EstimaterConstruction quoting and job tracking for contractors, on a Laravel and Firebase stack.
Related fixes
Back end
composer require laravel/horizon fails: ext-pcntl is missing
laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system
Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.
3 causes, each with a fixBack end
Laravel insert fails with 'Field user_id doesn't have a default value'
The insert works when the column is removed or made nullable
Error 1364 means Laravel sent an INSERT without a value for a NOT NULL column that has no default, and MySQL strict mode refuses it.
3 causes, each with a fixBack end
php artisan serve starts but the app is not reachable, or the .env is ignored
Server stops right after start with a non-zero exit code when --port is given and the port is busy
php artisan serve listens on 127.0.0.1 port 8000 by default.
4 causes, each with a fixBack end
Laravel migration cannot drop a column that has a foreign key
Error on rename of '%s' to '%s' (errno: %d - %s)
MySQL refuses to drop a column while a foreign key constraint still uses it.
2 causes, each with a fixBack end
Laravel: distinct() and count() give the total instead of the unique count
select('city')->distinct()->count() ignores the select
Laravel builds the count from the column you pass to count(), not from select().
2 causes, each with a fixBack end
Laravel Eloquent query for a column that is X or NULL
where('column', null) returns no rows
Wrap the pair in a closure: where(function ($q) { $q->where('col', $x)->orWhereNull('col'); }).
3 causes, each with a fix