MySQL ERROR 2002 "Can't Connect to Local MySQL Server Through Socket": The Fix on EC2, Amazon Linux 2023, RDS and Docker

ERROR 2002 (HY000): Can't connect to local MySQL server through socket means the mysql client tried to reach a database on the same machine, through a special file called a socket, and the file wasn't there. Either no MySQL server is running on this machine, or the server you want is somewhere else. The fix depends on which: start the local server with sudo systemctl start mariadb (or mysqld), or tell the client where the real server is with -h. The case that catches AWS users is the second one: on an EC2 server, mysql -u admin -p without -h doesn't connect to your RDS database at all; it looks for a local server, finds none, and reports this error. And here's the detail that makes it maddening: to a MySQL client, localhost means the socket, so -h localhost -P 3307 ignores the port and fails the same way, while -h 127.0.0.1 uses the network. This page covers each cause with its exact message, the socket paths that differ between MariaDB and MySQL, where Amazon Linux 2023 logs a server that won't start, and MySQL in Docker.

Ethan, a developer, opened a terminal on the EC2 server that runs the booking app for his friend Jake's phone repair shop, to check something in the RDS database. He typed mysql -u admin -p, entered the password, and got ERROR 2002. The database was fine. He'd asked the wrong machine.

New to these terms? A socket here is a file that a MySQL server creates on its own machine, so local programs can talk to it without the network. An EC2 server and an RDS database are two different machines, so a socket can never connect them.

What the error means, word by word

The error names the file it looked for, and the number at the end says what went wrong. These are the two versions you'll see:

ERROR 2002 (HY000): Can't connect to local server through socket '/var/lib/mysql/mysql.sock' (2)
ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)

The first comes from the MariaDB client that Amazon Linux 2023 installs as mysql; the second from Oracle's MySQL client. The (2) is the operating system's "no such file or directory": the socket file doesn't exist, which almost always means no server has created it. So ERROR 2002 is never about passwords or permissions on the database side. It's about where the client looked.

Four situations produce it, each with a different fix:

The RDS mistake: no -h means "this machine"

Here's what Ethan ran on his EC2 server, which has the mysql client installed but no database server:

mysql -u admin -p

ERROR 2002 (HY000): Can't connect to local server through socket '/var/lib/mysql/mysql.sock' (2)

Without -h, the client assumes the database is on the machine you're typing on, and goes looking for its socket file. To reach RDS, give the endpoint, the address shown on the database's page in the RDS console:

mysql -h shop-db.c1abcdexample.us-east-1.rds.amazonaws.com -u admin -p

If that now fails differently, with a timeout or ERROR 2003, you've moved on to the network: the security group or the route between the EC2 server and the database, which our RDS connection guide covers. That's progress: the client is finally knocking on the right door.

Jake: "So it was looking for the database in the wrong building?"

Ethan: "In this building's basement. The database lives across town, and I hadn't given it the address."

A local server that isn't running

If MySQL or MariaDB is supposed to run on this machine, the error usually means it's stopped. On Amazon Linux 2023 with MariaDB:

systemctl is-active mariadb

inactive

Start it, and make it start at every boot, then try again:

sudo systemctl enable --now mariadb
sudo mysql -N -e "SELECT VERSION();"

Created symlink /etc/systemd/system/mysql.service → /usr/lib/systemd/system/mariadb.service.
Created symlink /etc/systemd/system/mysqld.service → /usr/lib/systemd/system/mariadb.service.
Created symlink /etc/systemd/system/multi-user.target.wants/mariadb.service → /usr/lib/systemd/system/mariadb.service.
10.11.19-MariaDB

Notice the first two lines. On Amazon Linux 2023, the names mysqld and mysql only exist as aliases after you enable mariadb. Older tutorials tell you to run sudo systemctl start mysqld, and on a fresh install you get this instead:

Failed to start mysqld.service: Unit mysqld.service not found.

Use mariadb as the name, and both old commands work from then on. If systemctl is-active says active and you still get ERROR 2002, the server and the client disagree about the socket path; see the section on paths below.

Jake: "Why would it have two names?"

Ethan: "MariaDB took over from MySQL on a lot of Linux systems, so it answers to the old names too. But only once you've switched it on properly."

A server that won't start: read its error log

When the server fails on startup, systemctl gives you the familiar unhelpful line, and the client keeps reporting ERROR 2002:

Job for mariadb.service failed because the control process exited with error code.
See "systemctl status mariadb.service" and "journalctl -xeu mariadb.service" for details.

On Amazon Linux 2023, MariaDB writes its real errors to its own file, set in /etc/my.cnf.d/mariadb-server.cnf, not only to the journal:

sudo grep ERROR /var/log/mariadb/mariadb.log | tail -5

For a mistyped setting, the first of those lines names it exactly. Here someone wrote innodb_buffer_pool_size=notanumber in a file under /etc/my.cnf.d/:

2026-10-13 23:47:42 0 [ERROR] Unknown suffix 'n' used for variable 'innodb-buffer-pool-size' (value 'notanumber'). Legal suffix characters are: K, M, G, T, P, E
2026-10-13 23:47:42 0 [ERROR] /usr/libexec/mariadbd: Error while setting value 'notanumber' to 'innodb-buffer-pool-size'
2026-10-13 23:47:42 0 [ERROR] Parsing options for plugin 'InnoDB' failed. Disabling plugin
2026-10-13 23:47:42 0 [ERROR] Unknown/unsupported storage engine: InnoDB
2026-10-13 23:47:42 0 [ERROR] Aborting

Don't let the "Unknown/unsupported storage engine" line scare you; your data is fine. It's a side effect of the bad setting, which stopped the storage engine from loading. The other failure you'll often meet is ownership: after copying a data folder in by hand, /var/lib/mysql belongs to root and the server can't write to it:

2026-10-13 23:47:46 0 [ERROR] mariadbd: Can't create/write to file './ddl_recovery.log' (Errcode: 13 "Permission denied")
2026-10-13 23:47:46 0 [ERROR] DDL_LOG: Failed to create ddl log file: ./ddl_recovery.log
2026-10-13 23:47:46 0 [ERROR] Aborting

Whatever the log says, the recovery follows the same order:

1. Read the first [ERROR] line of the latest start; the later ones are usually its consequences.
2. Fix what it names: the setting in /etc/my.cnf.d/, or the owner with sudo chown -R mysql:mysql /var/lib/mysql.
3. Start it again with sudo systemctl start mariadb.
4. Check it with systemctl is-active mariadb, then connect.

Ethan: "The error you see in the terminal is never the real one. The real one is in the log."

Jake: "Like a customer saying 'the phone's broken' when the story is 'I dropped it in the sink'."

Socket paths: why the error shows different files

MariaDB and Oracle's MySQL use different default socket paths, which is why the answers you find online quote different files. The path in your error is where your client looked, not necessarily where the server put it:

To see where your server actually creates it, look in its configuration; on AL2023 that's the socket= line in /etc/my.cnf.d/mariadb-server.cnf. Then point the client at the same file with -S, or use TCP instead. Giving the wrong path produces exactly this error, with the path you gave:

sudo mysql -S /var/run/mysqld/mysqld.sock -e "SELECT 1"

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

localhost is not 127.0.0.1

Most programs treat localhost and 127.0.0.1 as the same thing. The MySQL client doesn't: localhost means "use the socket file", and 127.0.0.1 means "use the network". You can see it in the client's own status line:

sudo mysql -h localhost -N -e "status" | grep -iE "connection:|unix socket"

Connection:		Localhost via UNIX socket
UNIX socket:		/var/lib/mysql/mysql.sock

So when the socket is the problem, connecting with -h 127.0.0.1, or adding --protocol=TCP, skips it entirely. One surprise on AL2023's MariaDB: the root account signs in through the socket by system identity, which is why sudo mysql works without a password, and the same user over TCP is refused:

sudo mysql -h 127.0.0.1 -u root -e "SELECT 1"

ERROR 1698 (28000): Access denied for user 'root'@'localhost'

That's expected. Create a separate account with a password for anything that connects over the network, and keep root for local administration.

MySQL in Docker: always use 127.0.0.1

When MySQL runs in a container, its socket file is inside the container, where a client on your machine can't reach it. Publishing the port doesn't change that if the client uses localhost, because localhost still means the socket, even with a port given:

mysql -h localhost -P 13384 -u root -p

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

The client ignored -P 13384 completely. With 127.0.0.1, it uses the network and the port, and reaches the container:

mysql -h 127.0.0.1 -P 13384 -u root -p -N -e "SELECT @@version"

8.4.11

The same rule applies to application settings: write 127.0.0.1, not localhost, as the database host when the database is in a container. Our DynamoDB Local in Docker guide follows the same pattern for a different database.

Jake: "So localhost isn't always local?"

Ethan: "It's local, but it means 'through the file', and the file is inside the container. 127.0.0.1 means 'through the network', and the network is what Docker actually connected."

Five checks, in order

ERROR 2002 has a handful of causes, and guessing between them wastes time: people reinstall MySQL when the server was simply somewhere else. Run these checks in this order, because each one rules out a whole branch of the table at the top. Most of the time you'll stop at the first or second step, since the RDS mistake and a stopped server are by far the most common reasons you'll see this message. Here's the order you should follow before you change any setting:

1. Ask yourself where the database runs: this machine, a container, or another server such as RDS.
2. Another server: add -h with its address, and the error changes or disappears.
3. A container: use -h 127.0.0.1 and the published port.
4. This machine: run systemctl is-active mariadb (or mysqld) and start it if needed.
5. Still failing: read the server's error log, and compare the socket path in the error with the server's socket= setting.

If step two changes the error to a timeout or ERROR 2003, the client found the right address and the network is what's left; our EC2 connection guide walks through security groups and routes.

Troubleshooting by symptom

ERROR 2002 on an EC2 server, database is on RDS

You left out -h, so the client looked for a local server. Add -h with the RDS endpoint.

ERROR 2002 and systemctl says inactive

The local server isn't running. Run sudo systemctl enable --now mariadb (or mysqld).

Unit mysqld.service not found

On Amazon Linux 2023 the service is called mariadb. The mysqld and mysql names only exist after sudo systemctl enable mariadb.

ERROR 2002 right after a configuration change

The server failed to start. Read /var/log/mariadb/mariadb.log on AL2023 for the line it rejected.

ERROR 2002 with Docker and -h localhost

localhost means the socket, and the socket is inside the container. Use -h 127.0.0.1 and the published port.

ERROR 1698 Access denied for user root@localhost over TCP

MariaDB's root signs in through the socket. Use sudo mysql locally, or create a separate account with a password.

The socket path in the error doesn't exist on this machine

Your client and server use different defaults. Check the server's socket= setting and pass it with -S, or use TCP.

MySQL ERROR 2002: frequently asked questions

Ethan added the endpoint, -h shop-db..., and was in the RDS database a second later. He also saved the command as a shell alias, so the next time he'd type shopdb instead of remembering the address. Jake's verdict: "So the error was really 'I looked in your basement and there's no database there.'" Ethan said that was a better error message than the real one.

Revision note. Written October 13, 2026, for Amazon Linux 2023 with MariaDB 10.11 and for MySQL 8.4. There's an old saying about barking up the wrong tree; ERROR 2002 is the client doing exactly that, and one -h points it at the right one.