How to Fix MySQL Connection Errors on a VPS in 2026

0
(0)

MySQL connection errors on a VPS usually have a precise code behind the generic “cannot connect” message. The four you will see most often are 2002 (local socket), 2003 (TCP host), 1045 (access denied) and “MySQL server has gone away” (often 2006, sometimes 2013). MariaDB uses the same client codes in ordinary setups, so this guide applies to both.

Read the exact number and the hostname or socket in the message before you change bind-address or a user password. The wrong fix can expose the database or lock you out. This is a troubleshooting walkthrough, not a sizing guide. For hardware and workload planning, use the MySQL VPS guide or the MariaDB VPS guide.

Identify the error before you change anything

Error Typical message What it usually means
2002 Can’t connect to local MySQL server through socket The client used a Unix socket, and the server is down or the socket path is wrong
2003 Can’t connect to MySQL server on ‘host’ The client used TCP, and nothing accepted the connection on that host and port
1045 Access denied for user … The server is reachable; the user, password or host part of the account does not match
2006 or “gone away” MySQL server has gone away The connection was established, then the server closed it, timed it out, or rejected a packet
2013 Lost connection to MySQL server during query The session died mid-query, often from a restart, a timeout, or a killed connection

A WordPress “Error establishing a database connection” can be any of the first three. Look in the web or application log, or test with the same host, user and database the app uses. Official client code lists are in the MySQL client error reference.

Error 2002: the local socket is missing or wrong

2002 means the client tried a Unix socket, usually because the host is localhost. On many systems, localhost is not the same as 127.0.0.1. The first uses the socket; the second uses TCP.

See also  Managed vs Unmanaged VPS in 2026: Pros, Cons and Cost

Check whether the service is running and where the socket actually is:

sudo systemctl status mysql --no-pager
sudo systemctl status mariadb --no-pager
sudo ss -ltnp | grep -E '3306|mysql'
ls -l /var/run/mysqld/ /run/mysqld/ /var/lib/mysql/mysql.sock 2>/dev/null

If the unit is failed or inactive, read the service log before you change application credentials:

sudo journalctl -u mysql -u mariadb -e --no-pager
sudo tail -n 80 /var/log/mysql/error.log

A full disk, a bad configuration after an edit, InnoDB recovery, or a failed upgrade can keep the server from opening its socket. df -h and the error log are the first two checks. Start the service only after you know why it stopped.

If the server is running and the socket path in the log or in mysqld --verbose --help | grep socket does not match what the client uses, either point the client at the real socket or, when you meant TCP, use 127.0.0.1 and port 3306. Do not “fix” a down service by opening port 3306 on the public firewall.

Error 2003: TCP cannot reach the server

2003 is a network or listener problem: wrong host, wrong port, the server is bound only to localhost, or a firewall rejected the path. It is close in spirit to an SSH connection that never completes a handshake, and the same discipline helps: confirm the address, then the listener, then the firewall.

sudo ss -ltnp | grep 3306
sudo mysqladmin variables | grep -E 'bind_address|mysqlx_bind|port'
# or:
sudo mysqld --verbose --help 2>/dev/null | grep -E '^bind-address|^port'

If the application and the database are on the same VPS, the client should usually use localhost or 127.0.0.1. A 2003 in that case often means the service is down or is listening on a different port. If the app is on another VPS, confirm that the database server is listening on the private address you expect, and that you intended that setup.

Test from the same machine as the application:

nc -vz DB_HOST 3306
mysql --host=DB_HOST --port=3306 --user=APPUSER -p -e "SELECT 1"

A refused TCP port points at a stopped server or a bind address that does not include the target IP. A timeout points at a dropped firewall rule or a wrong route. Host firewalls and provider security groups both matter. The VPS security guide is explicit about this: do not expose database ports to the whole internet to make a connection test succeed.

See also  How to Run Your Own Git Server in 2026: Install and Configure a Git Server on a Linux VPS

If you need a remote administrative path, prefer an SSH tunnel or a WireGuard tunnel and keep MySQL on a private address. Changing bind-address to 0.0.0.0 without a tight firewall is not a troubleshooting step.

Error 1045: the server answered, then denied the account

1045 means you reached MySQL or MariaDB and it rejected the credentials. The account is a combination of user name, password and host. 'app'@'localhost' is not the same account as 'app'@'127.0.0.1' or 'app'@'%'.

From a working administrative login on the server, inspect the account without printing passwords into a ticket:

SELECT user, host FROM mysql.user WHERE user = 'app';
SHOW GRANTS FOR 'app'@'localhost';

Compare that host column with the client address the server actually sees. An application on the same VPS that connects through TCP may present as 127.0.0.1, not localhost. A container may present a bridge address you never created a user for.

Check the application config next: WordPress wp-config.php, a .env file, or a connection string. A typo, an old password after a rotation, and a leftover root password from a tutorial are more common than a “corrupt grant table.” Reset the password with the server’s official procedure for your version, then update the application and retry one client at a time.

On Ubuntu, the local root account often uses the auth_socket or unix_socket plugin, so sudo mysql works and a password from a tutorial does not. That is expected. Create a dedicated application user with a password and the right host, and leave the socket-based administrator for maintenance. Do not disable authentication plugins or create 'app'@'%' with a weak password as a shortcut. If you cannot log in as an administrator at all, use the documented recovery path for a local socket, not a public bind change.

Server has gone away: 2006 and 2013

These errors mean the connection existed and then dropped. Common causes are a server restart, a wait timeout, a packet larger than max_allowed_packet, a query longer than net_read_timeout or net_write_timeout, or an idle connection that the server or a proxy closed.

On the server:

SHOW GLOBAL VARIABLES LIKE 'max_allowed_packet';
SHOW GLOBAL VARIABLES LIKE 'wait_timeout';
SHOW GLOBAL VARIABLES LIKE 'max_connections';
SHOW GLOBAL STATUS LIKE 'Threads_connected';
SHOW GLOBAL STATUS LIKE 'Aborted_connects';

If a backup, import or large blob fails only on that job, max_allowed_packet is the first suspect. Raise it carefully and only as far as the job needs. If connections drop during the night, look at log rotation, unattended upgrades, OOM kills and scheduled restarts. journalctl and the Linux monitoring guide help you catch a restart you did not notice.

See also  KVM vs Hyper-V in 2026: Virtualization for VPS Hosting

Application-side connection pools can also hold a handle long after the server closed it. A “gone away” on the first query after idle time often needs a pool validation query, not a larger packet size. Lost connections mid-query (2013) deserve a look at slow queries and disk I/O, not only at the timeout numbers.

A related but different error is 1040, too many connections. That is capacity or a leak, not a bad password. Check max_connections, connected threads, and whether the application opens a new connection on every request.

A calm test sequence

Use the same host string as the application, then change one thing at a time:

# socket path (localhost on many systems)
mysql --user=APPUSER --password --socket=/var/run/mysqld/mysqld.sock -e "SELECT 1"

# TCP on the same VPS
mysql --host=127.0.0.1 --port=3306 --user=APPUSER --password -e "SELECT 1"

If the command-line client works and the application fails, the application config is wrong, or it is connecting from a different network namespace, such as a container. If both fail with 1045, stay on accounts and passwords. If both fail with 2002 or 2003, stay on the service, socket, bind address and firewall.

Record the error code, the host value, and whether the service was up. That short note is more useful than a reboot. After the site works again, confirm backups still run and that 3306 is not listening on a public interface. The website hosting guide is a reasonable place to return if the app and database share one VPS and you want a clean layout of services.

Frequently asked questions

Why does localhost fail with 2002 while 127.0.0.1 works?

The client is using a Unix socket for localhost and TCP for 127.0.0.1. The server may be listening on TCP while the socket path is missing, or the reverse. Point the application at the method you actually configured, and keep both consistent after upgrades.

Should I set bind-address to 0.0.0.0 to fix 2003?

Not as a first step, and not without a firewall that allows only the intended private sources. If the app is local, bind to localhost and fix the local socket or service instead.

Can a full disk cause all of these errors?

Yes. A full disk can stop the server from starting (2002 or 2003), and it can also cause later failures that look like “gone away” when the server cannot write. Check df -h early.

Is “server has gone away” always a max_allowed_packet problem?

No. It is one common cause for large queries or imports. Timeouts, restarts, killed connections and stale pool handles are just as likely. Read the timing and the server log before you raise the packet size.

Do these codes mean the same thing on MariaDB?

In ordinary VPS setups, yes. The client still reports 2002, 2003, 1045 and 2006. The service name, socket path and log file may differ, so use the unit and paths that exist on your image.

Sources

Was this guide helpful?

Rate this guide from 1 to 5 stars.

Average rating: 0 / 5. Ratings: 0

No ratings yet. Be the first to rate this guide.

Leave a Comment