A MySQL client-side connection error triggered when the client fails to reach the local server through its UNIX socket due to mismatched socket paths, missing daemon, or permission problems.
MySQL Error 2010 (CR_LOCALHOST_CONNECTION) means the client cannot connect to the local MySQL server via its UNIX socket. Confirm that mysqld is running, match the socket path in my.cnf, and reconnect using the correct parameters to resolve the issue.
Localhost via UNIX socket
MySQL Error 2010 appears when a client attempts to connect to localhost through a UNIX socket but the handshake never begins. The client library cannot open the designated socket file, so it returns the CR_LOCALHOST_CONNECTION code before any authentication step.<\/p>
The message usually looks like: ERROR 2010 (CR_LOCALHOST_CONNECTION): Localhost via UNIX socket<\/code>. Although the error is client-side, it flags underlying server, path, or permission issues that must be fixed before applications can run queries.<\/p>
Why does this error matter?<\/h3>Applications that rely on local MySQL connections will fail fast, blocking deployments, CI pipelines, and data services. Production outages can occur if monitoring agents, API backends, or ETL jobs lose access to the database.<\/p>
Resolving the socket problem quickly restores connectivity and prevents cascading failures across dependent services.<\/p>
What Causes This Error?<\/h3>MySQL clients first try the UNIX socket when host is localhost<\/code>. If the socket file is missing, mismatched, or restricted, the connection attempt aborts with error 2010.<\/p>
Common triggers include stopped mysqld<\/code>, custom socket paths in my.cnf<\/code>, stale socket files after a crash, SELinux or AppArmor blocks, and incorrect client parameters passed by ORMs or CLI tools.<\/p>
How to Fix MySQL Error 2010<\/h3>Verify the MySQL daemon is running, confirm the socket path in both server and client configs, and test a manual connection using the explicit --socket=<\/code> option. Restart the server to regenerate a missing socket file if needed.<\/p>
Adjust file permissions so the connecting Unix user can read and write the socket. On SELinux systems, relabel the file or set the proper boolean to permit local database access.<\/p>
Common Scenarios and Solutions<\/h3>Stopped server:<\/strong> Start MySQL with systemctl start mysqld<\/code> or mysql.server start<\/code> on macOS.<\/p>
Mismatched socket path:<\/strong> Align [client]<\/code> and [mysqld]<\/code> sections in /etc/my.cnf.d\/mysqld.cnf<\/code> or ~/my.cnf<\/code>.<\/p>
Docker compose setup:<\/strong> Map port 3306 and connect via TCP 127.0.0.1<\/code> instead of UNIX socket.<\/p>
Galaxy users:<\/strong> In the Galaxy connection dialog, set Host to 127.0.0.1<\/code> or provide the socket path so the editor bypasses default resolution logic.<\/p>
Best Practices to Avoid This Error<\/h3>Keep server and client socket paths consistent across environments. Use environment variables or a shared .my.cnf<\/code> snippet committed to version control.<\/p>
Automate health checks that validate mysqld<\/code> status and socket presence. Include a restart policy in systemd or Docker to recover from crashes.<\/p>
When distributing applications, prefer TCP connections to 127.0.0.1<\/code> to remove socket path dependencies.<\/p>
Related Errors and Solutions<\/h3>ERROR 2002 (CR_CONNECTION_ERROR):<\/strong> Triggered when the client cannot connect to the server over any protocol, including TCP. Check host, port, and firewall.<\/p>
ERROR 2003 (CR_CONN_HOST_ERROR):<\/strong> Indicates a failure to reach a remote host. Ensure the TCP port is open and mysqld listens on 0.0.0.0.<\/p>
ERROR 1045 (ER_ACCESS_DENIED_ERROR):<\/strong> Occurs after the socket is opened but the login fails. Verify user credentials and grants.<\/p>
localhost<\/code> as a request for UNIX socket because local sockets are faster and bypass the TCP stack.<\/p>How do I force MySQL to use TCP instead of a socket?<\/h3>Add --protocol=TCP<\/code> or set Host to 127.0.0.1<\/code>. This disables socket resolution for that session.<\/p>
Can I delete a stale socket file safely?<\/h3>If mysqld<\/code> is confirmed stopped, removing the orphaned socket is safe. The server recreates it on the next start.<\/p>
Does Galaxy handle socket path mismatches automatically?<\/h3>Galaxy surfaces connection errors immediately and lets you specify the socket or switch to TCP, helping you resolve path issues without manual CLI flags.<\/p>
.avif)
.avif){kind=logo}
