Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Laravel cannot find the database host: getaddrinfo failed

ErrorSQLSTATE[HY000] [2002] php_network_getaddresses: getaddrinfo failed: Name or service not known

Short 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.

  • Applies to Laravel 12, PHP 8.3, MySQL 8.4, Docker Compose 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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.mysql
  2. 2Match what you see, then jump to its fix

    1. 1The host printed above differs from DB_HOST in your .env.A cached config still holds the old hostFix
    2. 2DB_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. 3Same 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

What does the error look like?

  • SQLSTATE[HY000] [2002] php_network_getaddresses: getaddrinfo failed: Name or service not known
  • SQLSTATE[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.host

2Fix

Clear the cache, or rebuild it after correcting .env.

php artisan config:clear
# production: rebuild afterwards
php artisan config:cache

3Verify

Run a query from the command line.

php artisan db:show

Confirmed by laravel.com

Did this fix it?

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 ps

2Fix

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=3307

3Verify

Connect with the same values.

php artisan db:show

Confirmed by docs.docker.com

Did this fix it?

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.internal

2Fix

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/app

3Verify

Clear config and test again.

php artisan config:clear
php artisan db:show

Confirmed by laravel.com

Did this fix it?

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:

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.