Access denied for user 'homestead'@'localhost' (using password: YES)
When running php artisan migrate in a local Laravel environment, encountering the error Access denied for user 'homestead'@'localhost' (using password: YES) usually points to a misconfiguration in how the application connects to the database server. This is particularly common when using Homestead or similar Vagrant-based setups on macOS.
The core of the issue lies in the distinction between connection protocols. The MySQL client attempts to connect via TCP/IP by default when you set DB_HOST=localhost. However, many development environmentsâespecially those leveraging shared memory or Unix sockets for performanceâare configured to prefer socket connections. When your .env file specifies localhost, Laravel resolves this to a hostname that requires a network stack connection. If the MySQL server is configured to only accept local socket connections or if the TCP/IP port isn't listening on the expected interface, the handshake fails even if the credentials are correct.
Changing the Host Configuration
A common and effective fix involves changing the host from localhost to 127.0.0.1. In your .env file, update:
DB_HOST=localhost
to:
DB_HOST=127.0.0.1
Consequently, in app/config/database.php, ensure the default fallback also uses the IP address:
'host' => env('DB_HOST', '127.0.0.1'),
By explicitly using an IPv4 loopback address, you bypass potential hostname resolution ambiguities. The TCP/IP protocol is often more robust for initial connection attempts in development environments than socket-based connections, which can be finicky if the MySQL process isn't configured to listen on the specific Unix socket file your application expects (often /tmp/mysql.sock).
Verifying Database Connectivity
Before assuming a configuration error, it is prudent to verify that the database server is actually accepting connections with the provided credentials. You can test this directly from the command line using mysqladmin.
Run the following command in your terminal:
mysqladmin -u homestead -p status
When prompted, enter secret. If successful, you will see output indicating the server's uptime, thread count, and query statistics. As noted in troubleshooting logs, a response like Uptime: 21281 confirms the server is running and that the credentials are valid for TCP connections. This step rules out authentication issues and isolates the problem to the connection method or socket configuration.
Configuring the Unix Socket
If switching to 127.0.0.1 does not resolve the issue, the next logical step is to address the socket configuration directly. MySQL servers can be configured to listen on a Unix socket file rather than (or in addition to) a TCP port. Laravel's default configuration includes a unix_socket setting:
'unix_socket' => '/tmp/mysql.sock',
However, if this path does not match the actual socket file created by your MySQL installation (which can vary based on Vagrant or Homebrew installations), the connection will fail even with correct passwords. You may need to locate the actual socket file using mysql_config --socket or check the MySQL error logs. Ensuring that the path in database.php matches the reality of your OS setup is critical for avoiding handshake errors.
Why This Matters in Development
Understanding these nuances prevents brittle development environments where migrations fail silently or with confusing errors. By explicitly defining the host as 127.0.0.1, you ensure a direct TCP connection that is easier to debug via standard tools like mysqladmin. Additionally, verifying the Unix socket path ensures compatibility with systems that rely on shared memory for inter-process communication.
If you find yourself managing multiple environments or moving from Vagrant to native MySQL setups, maintaining consistent configuration across these layers becomes essential. For more advanced database management within Laravel ecosystems, resources from https://laravelcompany.com can provide further insights into optimizing your data layer architecture.