PDOException SQLSTATE HY000 2002 Can't connect to local MySQL server through socket ' /var/run/mysqld/mysqld.sock' (2)

PDOException SQLSTATE HY000 2002 Can't connect to local MySQL server through socket ' /var/run/mysqld/mysqld.sock' (2)

September 26, 2026 · Illustrated author avatarBy Stefan Bogdanescu
PDOException SQLSTATE HY000 2002 Can't connect to local MySQL server through socket ' /var/run/mysqld/mysqld.sock' (2)

Solving “Can’t Connect to Local MySQL Server” Error in Magento 2

If you’re facing the SQLSTATE [HY000] [2002] Can’t connect to local MySQL server error while setting up your Magento 2 instance, this guide will help you troubleshoot and resolve the issue.

Understanding the Error

The error message suggests that there’s a problem with the MySQL connection. The system is trying to reach the MySQL server through the specified socket path (/var/run/mysqld/mysqld.sock), but it can’t establish a connection.

There could be several reasons for this:

  1. The MySQL service might not be running.
  2. There may be network connectivity issues between your PHP and MySQL servers.
  3. The MySQL server configuration could be incorrect or incompatible with the environment.

Troubleshooting Steps

1. Check if MySQL is Running

Open a terminal and type:

sudo systemctl status mysql

If the service isn’t active, start it using:

sudo systemctl start mysql

2. Verify Network Connectivity

Make sure that both your PHP and MySQL servers are running on the same machine or can communicate over the network.

Use ping command to check if you can reach the MySQL server:

ping <mysql-server-ip>

3. Inspect MySQL Configuration

Check the MySQL configuration file (usually located at /etc/mysql/my.cnf) for any errors or misconfigurations. Ensure that the socket path specified matches the actual location.

Look for lines like these in your my.cnf:

socket = /var/run/mysqld/mysqld.sock

4. Verify MySQL User Credentials

Ensure that the database credentials (username, password, and host) defined in your Magento installation are correct.

Open your app/etc/env.php file and look for the 'db' section:

'db' => [
    'table_prefix' => '',
    'connection' => [
        'default' => [
            'host' => '127.0.0.1',
            'username' => 'root',
            'password' => 'secret_password',
            'dbname' => 'magento',
            'active' => '1',

Ensure the host, username, and password match what’s configured in your MySQL server.

Debugging Best Practices

Remember to clear Magento cache and reindex before running any setup commands. You can use the following commands:

php bin/magento cache:clean
php bin/magento indexer:reindex

Conclusion

This guide provides a comprehensive overview of how to troubleshoot and resolve the “Can’t connect to local MySQL server” error in Magento 2.

Key takeaways include ensuring that your MySQL service is running, verifying network connectivity between PHP and MySQL servers, checking MySQL configuration for any errors or misconfigurations, and validating MySQL user credentials defined in your Magento installation.

If you’re still facing issues after following these steps, consider reaching out to the official Magento 2 support resources or referring to the Laravel Company blog for more detailed technical guides.

Magento 2 Database Configuration Errors

Our network