MySQL service is stopped or was never started after a server reboot — `systemctl is-active mysql` returns `inactive`.. The socket file path in the client config (`[client]` section of my.cnf) does not match the path MySQL actually created (`[mysqld]` section). Common after installing multiple MySQL versions or switching from MariaDB.. MySQL attempted to start but failed silently due to a full disk — check `df -h /var/lib/mysql` and the error log at `/var/log/mysql/error.log`.. The directory `/var/run/mysqld/` was removed during cleanup or a tmpfiles.d sweep after reboot, so MySQL cannot create its socket file even if the service starts.. AppArmor or SELinux is blocking MySQL from writing the socket file to the configured path — `dmesg | grep -i denied` shows the block.. A Docker or WSL2 environment where the MySQL socket is inside the container but the client runs on the host, pointing to a non-existent host-side path.

Step 1: Check if MySQL is running: `systemctl status mysql`. If the output shows `inactive (dead)`, the service is down. On older systems use `service mysql status`.. Step 2: If stopped, start it: `sudo systemctl start mysql`. Watch for errors with `sudo journalctl -u mysql -n 50 --no-pager`. If it fails to start, the journal shows the root cause (disk full, config syntax error, InnoDB corruption).. Step 3: Verify disk space on the MySQL data directory: `df -h /var/lib/mysql`. If usage is at 100%, free space or extend the volume before restarting.. Step 4: Confirm the socket path the server uses: `grep -r 'socket' /etc/mysql/` — look for the `[mysqld]` section. Then confirm the client matches: the `[client]` section should list the same path. If they differ, add `socket = /var/run/mysqld/mysqld.sock` (or whatever the server uses) under `[client]` in `/etc/mysql/my.cnf`.. Step 5: If the socket directory is missing, recreate it with correct ownership: `sudo mkdir -p /var/run/mysqld && sudo chown mysql:mysql /var/run/mysqld`, then restart MySQL.. Step 6: As a workaround, connect via TCP instead of socket: `mysql -h 127.0.0.1 -P 3306 -u root -p`. In dbt profiles.yml, set `host: 127.0.0.1` instead of `localhost` — MySQL treats `localhost` as a socket connection, while `127.0.0.1` forces TCP.. Step 7: If MySQL is in Docker, ensure the socket is mounted to the host: `docker run -v /var/run/mysqld:/var/run/mysqld mysql:8.0`, or switch all clients to TCP connections on the mapped port.

Critical severityconnection

MySQL Error:
2002

What does this error mean?

Error 2002 (CR_CONNECTION_ERROR) means the MySQL client tried to connect via a Unix domain socket file and failed — either because the file does not exist, or because nothing is listening on it. This typically happens when MySQL is stopped, crashed, or never started after a reboot. In data-pipeline context you see this when ADF self-hosted integration runtime, dbt, or Airflow operators attempt a localhost connection to MySQL: the task fails immediately without retry because the socket is a local filesystem object, not a network timeout. The symptom is instant failure with the message "Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)" — the trailing (2) is the OS errno for ENOENT (file not found).

Common causes

1MySQL service is stopped or was never started after a server reboot — `systemctl is-active mysql` returns `inactive`.
2The socket file path in the client config (`[client]` section of my.cnf) does not match the path MySQL actually created (`[mysqld]` section). Common after installing multiple MySQL versions or switching from MariaDB.
3MySQL attempted to start but failed silently due to a full disk — check `df -h /var/lib/mysql` and the error log at `/var/log/mysql/error.log`.
4The directory `/var/run/mysqld/` was removed during cleanup or a tmpfiles.d sweep after reboot, so MySQL cannot create its socket file even if the service starts.
5AppArmor or SELinux is blocking MySQL from writing the socket file to the configured path — `dmesg | grep -i denied` shows the block.
6A Docker or WSL2 environment where the MySQL socket is inside the container but the client runs on the host, pointing to a non-existent host-side path.

How to fix it

1Step 1: Check if MySQL is running: `systemctl status mysql`. If the output shows `inactive (dead)`, the service is down. On older systems use `service mysql status`.
2Step 2: If stopped, start it: `sudo systemctl start mysql`. Watch for errors with `sudo journalctl -u mysql -n 50 --no-pager`. If it fails to start, the journal shows the root cause (disk full, config syntax error, InnoDB corruption).
3Step 3: Verify disk space on the MySQL data directory: `df -h /var/lib/mysql`. If usage is at 100%, free space or extend the volume before restarting.
4Step 4: Confirm the socket path the server uses: `grep -r 'socket' /etc/mysql/` — look for the `[mysqld]` section. Then confirm the client matches: the `[client]` section should list the same path. If they differ, add `socket = /var/run/mysqld/mysqld.sock` (or whatever the server uses) under `[client]` in `/etc/mysql/my.cnf`.
5Step 5: If the socket directory is missing, recreate it with correct ownership: `sudo mkdir -p /var/run/mysqld && sudo chown mysql:mysql /var/run/mysqld`, then restart MySQL.
6Step 6: As a workaround, connect via TCP instead of socket: `mysql -h 127.0.0.1 -P 3306 -u root -p`. In dbt profiles.yml, set `host: 127.0.0.1` instead of `localhost` — MySQL treats `localhost` as a socket connection, while `127.0.0.1` forces TCP.
7Step 7: If MySQL is in Docker, ensure the socket is mounted to the host: `docker run -v /var/run/mysqld:/var/run/mysqld mysql:8.0`, or switch all clients to TCP connections on the mapped port.

Example log output

ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)
mysql.service - MySQL Community Server
   Loaded: loaded (/lib/systemd/system/mysql.service; enabled)
   Active: inactive (dead) since Sun 2026-05-11 03:14:07 UTC; 6h ago

Frequently asked questions

Where is the MySQL socket file located?

On Debian/Ubuntu it is typically `/var/run/mysqld/mysqld.sock`. On RHEL/CentOS or macOS Homebrew installs it is often `/tmp/mysql.sock`. Run `SHOW VARIABLES LIKE 'socket';` from an active connection, or check `grep socket /etc/mysql/my.cnf` when you cannot connect.

MySQL starts but the socket error persists — what now?

The client is pointing to a different socket path than the server created. Compare `[mysqld]` and `[client]` sections in my.cnf — they must list the same `socket` value. Alternatively, force TCP: `mysql -h 127.0.0.1 -P 3306 -u root -p` bypasses the socket entirely.

Why does error 2002 only happen with `localhost` and not `127.0.0.1`?

MySQL treats `localhost` as a request for a Unix socket connection, while `127.0.0.1` forces a TCP connection on port 3306. If the socket file is missing but MySQL is listening on TCP, `127.0.0.1` works while `localhost` fails. In dbt and application configs, switching to `127.0.0.1` is a common workaround.

How do I prevent error 2002 from recurring after server reboots?

Enable MySQL to start on boot: `sudo systemctl enable mysql`. Verify the socket directory is persistent — on systems using tmpfiles.d, add a config in `/etc/tmpfiles.d/mysql.conf` with `d /var/run/mysqld 0755 mysql mysql -` so the directory is recreated at boot before MySQL starts.

Source · dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html