Troubleshooting WordPress: "Error Establishing a Database Connection" on MySQL 8.4+ (macOS/MacPorts)

Chacha Nurholis — Fri, 06 Mar 2026 13:37:32 +0000

The Problem

The error usually stems from three main areas:

Networking: MySQL is running in "Socket-only" mode (ignoring TCP/IP ports).
Filesystem: Incorrect directory paths preventing MySQL from starting.
Authentication: A mismatch between MySQL’s modern encryption and PHP’s legacy requirements.

Step-by-Step Resolution

1. Fix the "Socket-Only" & Directory Configuration

By default, some MacPorts installations disable networking (skip-networking) and might have incorrect directory paths in my.cnf.

Action: Edit your my.cnf (usually in /opt/local/etc/mysql8/my.cnf) to ensure the server opens port 3306 and uses the correct data directory.

[mysqld]
# Ensure the data directory exists and is correct
datadir = /opt/local/var/db/mysql8
socket = /opt/local/var/run/mysql8/mysqld.sock

# Enable networking to allow DBeaver and Apps to connect via 127.0.0.1
bind-address = 127.0.0.1
port = 3306

# Crucial: Re-enable the legacy authentication plugin for MySQL 8.4+
mysql-native-password=ON

2. Solve the "Connection Refused" (Socket vs. Port)

Even if MySQL is running, WordPress might fail if it tries to connect via a port that isn't listening.

Symptoms: CLI works (via socket), but DBeaver and WordPress fail.
Fix: Check if port 3306 is listening using netstat -an | grep 3306. If empty, the my.cnf changes above and a service restart are required:

sudo port unload mysql8-server
sudo port load mysql8-server

3. Initialize Directory Permissions

If MySQL fails to start (the .sock file is missing), it’s likely a permission issue. MySQL needs to own the folders where it writes data and its socket file.

Action:

sudo chown -R _mysql:_mysql /opt/local/var/db/mysql8
sudo chown -R _mysql:_mysql /opt/local/var/run/mysql8

4. Bridge the Authentication Gap

MySQL 8.4+ uses caching_sha2_password, but WordPress's PHP library (mysqli) often requires the older mysql_native_password.

The Error: The server requested authentication method unknown to the client.
The Fix: You must manually downgrade the authentication method for your database user (including root) via the MySQL CLI.

Action:

-- Access via CLI
mysql -u root -p

-- Force the user to use the native password plugin
ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your_password';
FLUSH PRIVILEGES;

The Final WordPress Configuration

Once the database is listening on port 3306 and the user authentication is downgraded, update your wp-config.php:

define( 'DB_NAME', 'your_db_name' );
define( 'DB_USER', 'root' );
define( 'DB_PASSWORD', 'your_password' );

/** Use 127.0.0.1 to force TCP/IP connection */
define( 'DB_HOST', '127.0.0.1' );

Conclusion

Setting up WordPress on a modern stack requires more than just extracting files. You must ensure the Networking is open, Permissions are granted, and Authentication methods are compatible.

By following these steps, you move past the "Connection Error" and into the "Installation" screen, ready to build your site.

Forem: Chacha Nurholis