Magento website stopped working: SQLSTATE[HY000] [2002] Can't connect to local MySQL server through socket

Magento website stopped working: SQLSTATE[HY000] [2002] Can't connect to local MySQL server through socket

July 20, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Magento website stopped working: SQLSTATE[HY000] [2002] Can't connect to local MySQL server through socket

Magento Website Troubleshooting: Solving “SQLSTATE[HY000] [2002] Can’t connect to local MySQL server” Error

As an experienced developer, I understand the frustration that comes with a website suddenly stopping due to a database connection error like SQLSTATE[HY000] [2002] Can't connect to local MySQL server through socket '/var/lib/mysql/mysql.sock' (2). This issue typically arises from problems with your Magento installation’s database configuration or the underlying MySQL server.

Understanding the Error

The error message is quite explicit. It indicates that your Magento application cannot establish a connection to the local MySQL server via its socket file located at /var/lib/mysql/mysql.sock. The (2) at the end suggests it’s likely a permissions issue rather than a network problem or database server failure.

Troubleshooting Steps

1. Check MySQL Server Status

Before proceeding, ensure your MySQL server is running:

sudo systemctl status mysql

If it shows active (running), proceed to the next step. If not, start the service with:

sudo systemctl start mysql

2. Verify Socket File Permissions

The error mentions a permissions issue with the socket file. Check its ownership and permissions:

ls -l /var/lib/mysql/mysql.sock

If the owner is not mysql or the permissions are restrictive (like 0640 instead of 0777), change them accordingly:

sudo chown mysql:mysql /var/lib/mysql/mysql.sock
sudo chmod 777 /var/lib/mysql/mysql.sock

3. Inspect Magento’s Database Configuration

Open your app/etc/local.xml file and locate the <resources> section:

<resources>
    <db_is_utf8>true</db_is_utf8>
    <default_setup>
        <connection>
            <host><![CDATA[localhost]]></host>
            <username><![CDATA[your_username]]></username>
            <password><![CDATA[your_password]]></password>
            <dbname><![CDATA[your_database_name]]></dbname>
            <active>1</active>
        </connection>
    </default_setup>
</resources>

Ensure the <host>, <username>, and <password> values match your actual database setup. If you’ve changed any credentials recently, update them here.

4. Clear All Cache

Magento stores cache data that might be causing conflicts:

rm -rf var/cache/*
rm -rf var/session/*

After clearing the cache, restart your Magento application to see if the issue persists.

Final Thoughts and Next Steps

If you’ve executed all these steps and the error still occurs, consider checking your server’s firewall rules or network configuration for any blocks that might prevent the connection. You can also verify your MySQL server logs at /var/log/mysql/error.log for more specific details about the issue.

Remember to back up your database before making changes and test on a staging environment first if possible.

For further reading on Magento performance optimization and troubleshooting, I recommend checking out our guide on best practices.

Database Security API Configuration

Our network