Resolving Laravel Database Connection Error: Access Denied for User 'homestead'@'localhost'

Problem Background and Error Analysis

In Laravel 5.0 development environments, encountering the Access denied for user 'homestead'@'localhost' (using password: YES) error when executing php artisan migrate is a common issue. This error indicates that the application cannot connect to the MySQL database using the provided credentials. While the error message points to authentication failure, the root cause may involve multiple configuration layers.

Configuration Environment Verification

First, it's essential to verify the correctness of basic configurations. In Laravel projects, database connection settings are primarily defined through the .env file and config/database.php file. Typical configurations include:

// .env file configuration
APP_ENV=local
APP_DEBUG=true
DB_HOST=localhost
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret

// MySQL configuration in config/database.php
'mysql' => [
    'driver' => 'mysql',
    'host' => env('DB_HOST', 'localhost'),
    'database' => env('DB_DATABASE', 'homestead'),
    'username' => env('DB_USERNAME', 'homestead'),
    'password' => env('DB_PASSWORD', 'secret'),
    'unix_socket' => '/tmp/mysql.sock',
    'charset' => 'utf8',
    'collation' => 'utf8_unicode_ci',
    'prefix' => '',
    'strict' => false,
]

Even when these configurations appear correct, connection failures may still occur, requiring further investigation.

MySQL UNIX Socket Configuration Investigation

In Mac OS Yosemite systems, MySQL typically uses UNIX sockets for local connections. If the socket path specified in config/database.php doesn't match the actual path used by the MySQL service, connection failures will result.

First, determine the actual socket path used by MySQL:

mysql -u homestead -p
Enter password: secret
mysql> show variables like '%sock%';
+-----------------------------------------+-----------------------------+
| Variable_name                           | Value                       |
+-----------------------------------------+-----------------------------+
| performance_schema_max_socket_classes   | 10                          |
| performance_schema_max_socket_instances | 322                         |
| socket                                  | /var/run/mysqld/mysqld.sock |
+-----------------------------------------+-----------------------------+
3 rows in set (0.00 sec)

The query results show that MySQL actually uses /var/run/mysqld/mysqld.sock, while the configuration file specifies /tmp/mysql.sock. This mismatch is the primary cause of connection failure.

Correct the configuration:

// Update socket configuration in config/database.php
'mysql' => [
    // ... other configurations remain unchanged
    'unix_socket' => '/var/run/mysqld/mysqld.sock',
    // ...
]

Environment Variable Caching Issues

Laravel 5 introduced environment configuration caching. After modifying the .env file, you may need to clear the configuration cache for changes to take effect. If database configuration changes don't resolve the error, try the following command:

php artisan config:clear

This command clears cached configuration information, forcing Laravel to re-read the latest settings from the .env file.

Server Restart and Connection Testing

In some cases, particularly when database configurations are modified while the development server is running, restarting the server is necessary for new configurations to take effect:

// Stop the currently running server
Ctrl + C

// Restart the server
php artisan serve

Additionally, you can directly test the MySQL connection to verify configuration correctness:

mysqladmin -u homestead -p status
Enter password: secret

If MySQL running status information is returned, it indicates that the database service is running normally and credentials are correct.

Comprehensive Solution Implementation

Based on the above analysis, the complete steps to resolve this error include:

1. Confirm MySQL service is running normally
2. Check and correct the UNIX socket path in config/database.php
3. Verify database configurations in the .env file
4. Clear Laravel configuration cache: php artisan config:clear
5. Restart the development server
6. Re-execute the database migration command

By systematically investigating these key aspects, you can effectively resolve the Access denied for user 'homestead'@'localhost' error, ensuring that Laravel applications can properly connect to and operate databases.