Can’t Connect to Local MySQL Server Through /tmp/mysql.sock on macOS

I first recorded this error after installing MySQL with Homebrew and running mysql in Terminal:

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

The archived fix deleted the MySQL data directory before removing and reinstalling the formula. That can permanently destroy databases, and it is not a safe general solution. This reviewed guide takes a diagnostic-first approach instead.

August 2026 technical review: Homebrew formulae, MySQL releases, service details, and local configuration can change. Read the output from your own Mac before changing anything. If the databases matter, confirm that you have a usable backup before attempting disruptive recovery.

What the Socket Error Means

The mysql command is a client. It must connect to a running MySQL server process before it can authenticate a user or access a database.

On macOS and other Unix-like systems, a local MySQL client commonly uses a Unix socket file when no host is specified or when the host is localhost. The error means that the client could not reach a server through the socket path it tried. According to the official MySQL connection troubleshooting guide, the usual causes include a server that is not running or a client and server using different socket paths.

This is not automatically a password problem, and reinstalling MySQL does not identify the cause. Separate the possibilities before making a change:

1. the MySQL server is not running;
2. the server is running but uses another socket path;
3. the shell is using a client from a different MySQL installation or formula;
4. TCP works while the Unix-socket connection does not;
5. an option file overrides the expected socket, port, or data directory; or
6. the server cannot start because of a configuration, permission, or data-directory problem.

Before You Change Anything

Do not delete /tmp/mysql.sock, a Homebrew data directory, or any path under var/mysql as an opening step. Do not reinitialize the server, recursively change ownership, force-kill processes, or reinstall the formula before understanding the failure.

If a recovery step could alter the data directory, stop and make sure important databases are backed up. A filesystem copy taken without understanding whether the server is running is not a substitute for a tested database backup.

The commands below do not ask for or display a database password. Keep passwords out of shell commands, screenshots, issue reports, and copied configuration output.

1. Identify the Client and Homebrew Installation

Start with read-only inventory commands:

brew --version
brew --prefix
command -v mysql
mysql --version

brew --prefix discovers the active Homebrew prefix instead of assuming /opt/homebrew for Apple Silicon or /usr/local for Intel. command -v mysql shows which client the shell will run. The path and version should make sense together.

Now list installed MySQL-family formulae:

brew list --formula --versions |
  grep -E '^(mysql(@[^ ]+)?|mariadb(@[^ ]+)?|percona-server(@[^ ]+)?) '

No output means Homebrew does not currently list one of those formula names. More than one result means you must identify which server and client you intend to use. MariaDB, Percona Server, unversioned MySQL, and versioned MySQL formulae are not interchangeable simply because their client commands look similar.

Set a shell variable to the exact formula name reported on your Mac. The unversioned formula is shown here only as an example:

mysql_formula="mysql"
brew info "$mysql_formula"
brew --prefix "$mysql_formula"

If your installed formula is versioned, use that exact name, such as mysql@8.4, instead. The official Homebrew MySQL formula page records current formula caveats and available variants; brew info is the local source of truth for the installation you are inspecting.

2. Check Whether the Intended Server Is Running

Homebrew can report the services it manages for the current user:

brew services list
brew services info "$mysql_formula"

Look for the exact formula selected in the previous step. A stopped service explains why no socket was created. An error state means the server attempted to start and failed; repeatedly restarting it will not correct an invalid configuration or inaccessible data directory.

If the selected service is stopped and you intend to run it as a login service, the following is a corrective command:

brew services start "$mysql_formula"
brew services info "$mysql_formula"

brew services start changes service state and registers the formula to launch at login. The official Homebrew services documentation also documents brew services run for a temporary run without login registration. Do not add sudo to these commands for a normal per-user Homebrew service.

If startup fails, continue to the configuration and error-log checks below. Do not move directly to reinstalling or deleting data.

3. Make Sure the Client Matches the Selected Formula

Ask Homebrew for the selected formula’s actual prefix, then run its client explicitly:

formula_prefix="$(brew --prefix "$mysql_formula")"
printf 'Selected formula prefix: %s\n' "$formula_prefix"
"$formula_prefix/bin/mysql" --version

Compare that result with command -v mysql and mysql --version. If they identify different installations, you may be starting one formula while calling another formula’s client. Fixing that is a deliberate PATH or service-selection decision, not a reason to unlink, relink, or uninstall formulae blindly.

The selected installation can also report the socket and TCP port compiled into its client tools:

mysql_socket_path="$("$formula_prefix/bin/mysql_config" --socket)"
mysql_tcp_port="$("$formula_prefix/bin/mysql_config" --port)"
printf 'Client socket: %s\nClient TCP port: %s\n' \
  "$mysql_socket_path" "$mysql_tcp_port"
ls -l "$mysql_socket_path"

These are client defaults, not proof of the running server’s configuration. A missing file supports either “the server is not running” or “the server created its socket somewhere else.” An existing file still does not prove that the server behind it is healthy.

4. Test TCP and Unix-Socket Connections Separately

MySQL documents TCP/IP and Unix sockets as separate local transports. On Unix-like systems, localhost normally selects a Unix socket; 127.0.0.1 with --protocol=TCP selects TCP explicitly. See the official explanation of MySQL connection transport protocols.

Test TCP using the selected formula’s reported default port:

"$formula_prefix/bin/mysql" \
  --protocol=TCP \
  --host=127.0.0.1 \
  --port="$mysql_tcp_port" \
  --connect-timeout=5

Then test the selected client’s socket path explicitly:

"$formula_prefix/bin/mysql" \
  --protocol=SOCKET \
  --socket="$mysql_socket_path" \
  --connect-timeout=5

These commands test connection routes without placing a password on the command line. A MySQL prompt means the transport and authentication both worked. An “access denied” response means the client reached a MySQL server and authentication is now the separate issue. Another connection error means the transport still needs investigation.

If TCP reaches the server but the socket test fails, the server is running and the problem is likely the socket path or socket access. Once you connect through an already approved authentication method, these read-only SQL statements report the server’s active values:

SHOW VARIABLES LIKE 'socket';
SHOW VARIABLES LIKE 'port';

Use the server’s reported socket path for local socket clients, or align the server and client configuration deliberately. Do not copy credentials into the article’s diagnostic commands.

5. Check Option-File Overrides

MySQL clients and the server can read several option files. A [client] or [mysql] group can override the client socket, while a [mysqld] group can change the server socket, port, or data directory. Files read later can override earlier values.

Use help output to see which option files and groups the selected programs read:

"$formula_prefix/bin/mysql" --help
"$formula_prefix/bin/mysqld" --verbose --help

The official MySQL guide to using option files lists the Unix search order and explains how [client], [mysql], and [mysqld] differ. Homebrew’s current MySQL formula also warns that /etc/my.cnf or /etc/mysql/my.cnf left by another installation may interfere with startup.

Inspect only the relevant socket, port, datadir, and log-error settings. Do not publish an entire option file: it may contain account names, paths, or credentials. If you find an obsolete override, back up that configuration file and change only the setting you understand.

MySQL can validate startup configuration without running the server normally:

"$formula_prefix/bin/mysqld" --validate-config

The official server configuration validation documentation notes that a successful exit validates only checks available without normal startup. It does not prove that storage engines, plugins, permissions, or the data directory will work.

6. Distinguish Permission and Data-Directory Failures

When brew services info reports an error or the service immediately stops, the socket message is often a consequence of server startup failure. The missing socket is not the root cause.

The full server help output can show the effective datadir, log-error, and socket defaults after option-file processing:

"$formula_prefix/bin/mysqld" --verbose --help |
  grep -E '^(datadir|log-error|socket)[[:space:]]'

Review the actual MySQL error log before changing permissions or data. MySQL’s error-log documentation explains that the log records startup and shutdown events; its location can be changed with log-error, and a relative path is resolved under the data directory.

Treat these as separate findings:

• Permission denied: identify the exact file or directory named in the log and confirm which user runs the Homebrew service. Do not apply recursive chown or chmod commands to a database directory as a generic fix.
• Invalid or obsolete option: correct only the reported configuration entry, then rerun --validate-config before another start attempt.
• Missing or unexpected data directory: stop. Confirm the intended installation and backup history before creating, moving, or initializing anything.
• Upgrade incompatibility or damaged tables: use the recovery and upgrade procedure for the exact installed MySQL release. Back up recoverable data first and do not treat reinstalling the program files as database recovery.

Error logs can contain local usernames, hostnames, and filesystem paths. Review them locally and redact sensitive details before sharing an excerpt.

Match the Fix to the Diagnosis

The safest resolution depends on what the diagnostics show:

• If the intended Homebrew service is stopped, start that exact formula and confirm its state.
• If TCP works but the socket does not, discover the server’s active socket and align the client path.
• If the shell uses the wrong client, call the intended formula explicitly and then correct PATH deliberately.
• If an option file overrides one side of the connection, back up the file and align only the conflicting setting.
• If the server cannot access its configuration or data directory, investigate the exact logged failure before changing permissions.
• If the data directory may be damaged or incompatible, pause and plan a backed-up, version-specific recovery.

The original error looked simple, but it can describe several different conditions. A reliable fix comes from identifying which server, client, transport, configuration, and data directory are actually in use—not from deleting the data and starting over.