SQLSTATE[HY000] [2002] php_network_getaddresses: getaddrinfo failed: nodename nor servname provided, or not known

SQLSTATE[HY000] [2002] php_network_getaddresses: getaddrinfo failed: nodename nor servname provided, or not known

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Decoding the getaddrinfo failed Error in Laravel Migrations

When running php artisan migrate, you might encounter a cryptic error message:

SQLSTATE[HY000] [2002] php_network_getaddresses: getaddrinfo failed: nodename nor servname provided, or not known

This isn't just a generic database connection failure; it is a specific networking resolution issue occurring before your application even attempts to talk to MySQL. The error stems from PHP's inability to resolve the host address specified in your configuration. In this case, the root cause lies within the .env file settings for your local development environment.

The Root Cause: Misconfigured Hostnames

The error message explicitly states nodename nor servname provided, or not known. This indicates that the PHP process tried to perform a DNS lookup on the host string defined in your configuration but failed because the string was malformed or invalid.

Looking at the provided environment variables, the culprit is this line:

DB_HOST=http://localhost/

You are attempting to connect to MySQL using http://. This is a protocol mismatch. The DB_HOST configuration value should contain only the hostname and port (e.g., localhost, 127.0.0.1, or db.example.com). It must not include the mysql:// or http:// prefix, nor should it end with a trailing slash unless you are using a specific ORM adapter that expects a full URL string (which is rare for standard Laravel database connections).

When PHP receives http://localhost/, it attempts to treat this as a network address. Since http:// is not a valid hostname component, the underlying C-library function getaddrinfo throws the "nodename nor servname" error immediately upon trying to resolve the connection.

Correcting the Configuration

To fix this, you need to isolate the database host from the protocol and URL formatting. The DB_HOST environment variable should strictly define where the server lives.

Update your .env file with the following adjustments:

APP_ENV=local
APP_URL=http://localhost/
APP_DEBUG=true
APP_KEY=****

# Remove protocol and trailing slash
DB_HOST=localhost 
# Or use IP for better consistency in Docker setups
# DB_HOST=127.0.0.1 

DB_DATABASE=name-local
DB_USERNAME=root
DB_PASSWORD=

# Ensure the socket path is correct if using Unix sockets
UNIX_SOCKET=/tmp/mysql.sock

By setting DB_HOST to just localhost, PHP passes this clean string to the MySQL driver. The driver then correctly resolves localhost to the loopback interface (127.0.0.1) and attempts the connection based on the protocol inferred from the database configuration block (which defaults to TCP/IP unless a socket is explicitly used).

Understanding the Socket vs. TCP Conflict

Your .env file also defines a UNIX_SOCKET. This introduces a potential secondary issue if the host configuration remains ambiguous.

In MySQL, you can connect via a Unix socket or over a TCP/IP port (default 3306).

  • If DB_HOST is set to /tmp/mysql.sock, the driver attempts a socket connection directly.
  • If DB_HOST is set to a hostname like localhost or an IP address, the driver typically defaults to a TCP/IP connection unless explicitly told otherwise.

In your original configuration, you mixed a protocol URL (http://localhost/) with a socket path (UNIX_SOCKET = /tmp/mysql.sock). This inconsistency often confuses the database driver. If you intend to use a Unix socket, it is generally cleaner to omit DB_HOST or set it to an empty string while ensuring the socket path is correct:

DB_HOST=
UNIX_SOCKET=/tmp/mysql.sock

However, if your MySQL server is listening on the standard TCP port 3306, you should remove the UNIX_SOCKET line entirely and ensure DB_HOST contains a valid network address like localhost.

Why This Matters for Local Development

Running migrations locally requires a stable connection between your PHP CLI process and the database server. Misconfigured hostnames are a common source of frustration because they bypass standard error handling; the application crashes at the very first attempt to resolve the address.

Ensuring that DB_HOST contains a plain hostname or IP prevents the getaddrinfo failure. It allows the Laravel framework to proceed to the next stage: validating credentials and establishing the actual session with the database engine. Once the host is corrected, your php artisan migrate command should execute without triggering the network resolution error, allowing you to focus on schema changes rather than debugging environment variables.

Our network