Build your MySQL / MariaDB connection checklist

MYSQL / MARIADB · 3306

Build your MySQL / MariaDB connection checklist

Choose the error and client environment to get relevant checks and command examples. No hostname, username or password is needed.

This section does not execute commands or connect to a server. Replace the example hostname and port for your authorized environment. A shared link contains only the selected error, environment and client.

First checks by error type

Connection refused

Use this branch when the full message indicates connection refused. MySQL may report 2003/10061 and the MariaDB client may report 2002; if a socket path is named, select the local socket branch.

  1. Run the check from the machine or container network where the failing application runs.
  2. Compare the listening service with the application hostname and configured port.
  3. A missing listener or an explicit network rejection may be responsible; the error number alone is insufficient.

Next step: If TCP connects, return to the full application error. Otherwise, check the listener and permitted source network with the server administrator.

Connection timed out

Use this branch when the client waits for a connection and then times out.

  1. Check whether the application hostname resolves to the expected address.
  2. Compare VPN, private-network and cloud access rules with the application source network.
  3. Inspect the path before increasing a timeout; a timeout alone does not prove firewall blocking.

Next step: Keep your network result separate from an external port check. A private database may correctly be unreachable from the internet.

1045 — Access denied

Use this branch when the database rejects authentication.

  1. Verify that the client reaches the intended environment and server.
  2. Have an authorized administrator check the user/host account match, privileges and authentication method.
  3. Keep passwords out of support tickets; do not automatically retry failed logins.

Next step: Opening more ports does not diagnose an authentication failure after connecting. Recheck the original application request after correcting the account configuration.

2002 — Local socket connection

If the message names a socket path, a TCP test exercises a different transport.

  1. Establish whether the client and database run on the same machine.
  2. Compare the socket path expected by the client with the one used by the server.
  3. Compare with TCP only if your local server listens on TCP and the account is authorized for it.

Next step: Do not delete the socket file arbitrarily. Successful TCP access does not validate the socket path or permissions.

2005 — Unknown server host

If the hostname cannot be resolved, investigate name resolution first.

  1. Check the spelling and intended environment of the hostname.
  2. Resolve it inside the application network; a private DNS or container service name may not work externally.
  3. Compare the answer with the expected address; DNS success does not establish TCP or login success.

Next step: After resolution works in the correct network, continue with the same hostname and configured port.

Download the checklist for all cases

This is a diagnostic checklist, not confirmation of a root cause or a successful fix.

Sources and command documentation

2002, 2003 and 1045: what changes in a real experiment?

On 9 November 2026 we tested the MySQL 8.4.13 and MariaDB 11.4.13 clients against their respective servers in separate Linux Docker containers. Both ran the same four checks with no external network or published host ports. Checks used each container’s own loopback interface. Both containers and temporary databases were removed. These are reproducible controlled experiments, not customer incidents.

Two engines, eight verified outcomes
TransportMySQL 8.4.13MariaDB 11.4.13Interpretation
TCP 127.0.0.1:33072003 / HY0002002 / HY000No listener: connection refused. Check destination, port and listener first.
TCP 127.0.0.1:33061045 / 280001045 / 28000Deliberately wrong password: the server was reached and rejected authentication.
SOCKET /tmp/cybertool-absent.sock2002 / HY0002002 / HY000A nonexistent Unix socket path. Changing a TCP port does not fix this path.
TCP 127.0.0.1:3306SELECT 1 → 1; exit 0SELECT 1 → 1; exit 0Same server and port, correct temporary password: successful control.

The same refused TCP connection produced 2003 in the MySQL client and 2002 in the MariaDB client. A missing socket produced 2002 in both. Identify the client, transport and full message before choosing a fix. We caused 1045 with a wrong password here; account user/host matching or the authentication method can also cause it in a real system. These observations apply to the tested versions on Linux; a native Windows client was not tested.

Why localhost can mislead you inside Docker

If the application and database use separate containers, 127.0.0.1 in the application points to the application container itself. Use the Compose service name and container port on their shared Docker network, for example db:3306. A host mapping of 3307:3306 does not mean another container should use db:3307. Our experiment deliberately runs the client inside the database container, where 127.0.0.1 is appropriate. Repeat checks from the actual application network for a real incident.

Reproduce the experiment

Requires Python 3 and a running Docker daemon. Extract the kit and run the commands below. Each run creates one temporary container: a 1 GB memory limit for MySQL or 512 MB for MariaDB, and 1 CPU. It checks four outcomes and cleans up. The script does not print passwords or include them in result files. They exist in process/container environments while the lab runs and are visible to administrators with Docker access. Initial image downloads need internet; the lab network is disabled. Image tags can change; the two result JSON files record the tested versions and digests.

docker pull mysql:8.4
python3 mysql_connection_lab.py --engine mysql

docker pull mariadb:11.4
python3 mysql_connection_lab.py --engine mariadb

Kit with the lab script and recorded results · GitHub

References: MySQL connection troubleshooting · Docker Compose networking

One application, two errors: which check comes next?

Hypothetical example: a Windows application cannot connect to a database on an authorized private network. These are not captured server results or resolved customer incidents.

A — 2003 / Connection refused / 10061

The TCP connection was refused. From the application network, check the destination and configured port; compare the listener with the administrator. A successful check from another machine does not establish application connectivity.

Open this example’s checklist

B — 1045 / Access denied

The server rejected authentication. Verify the intended environment, then review the user/host account match and authentication method with the administrator. This message alone does not prove a wrong password.

Open this example’s checklist

Open the matching checklist to continue. Exposing a private database to the internet or disabling a firewall is not the fix proposed in either example.

Current web guide · cyber-tool.org