How to fix WordPress "Error establishing a database connection"

This problem is easily fixed. There are only 2 steps: (1) get the detailed error message; (2) fix the problem indicated by the error message. So ignore all the advice you have received so far. There are not 5 easy steps…there are just 2….find out more…fix the problem. It is simply idiotic to start changing database credentials, repairing the database, restoring the default WordPress files, etc., etc., etc. All of these shotgun techniques are unlikely to work. When the check engine light come on in your car do you simply start replacing parts? Of course not. You get the diagnostic code behind the idiot light (they are called idiot lights for a reason) and proceed accordingly. The same approach applies here. The famous "Error establishing a database connection" is simply an idiot light.

Step 1: Get the Detailed Error Message

For this you will need to modify wp-config.php in the root directory of your site.

Find this line…

define( 'WP_DEBUG', false );

and change it to

define( 'WP_DEBUG', true );

Now restart the site and you will see a detailed error message.

Step 2: Fix the problem indicated by the error message

Just like the check engine light in your car, any of a large number of issues may have caused the WordPress idiot light to come on. Below you will find a list of possible error messages and the indicated fixes. This list is by no means exhaustive.

Problem 1: SSL Connection required

Warning: mysqli_real_connect(): (HY000/9002): SSL connection is required. 
Please specify SSL options and retry. 
in /home/site/wwwroot/wp-includes/wp-db.php on line 1635
SSL connection is required. Please specify SSL options and retry.

This was the issue with my site. I was deploying WordPress to Azure in a Web App with the database in MySQL for Azure. MySQL for Azure requires a secure connection and by default WordPress uses an unencrypted connection.

The fix for this one is to add the following line of code to wp-config.php…

define ( 'MYSQL_CLIENT_FLAGS', MYSQLI_CLIENT_SSL);

This issue is a great example of why you need to get the detailed error message. You can search the hundreds of answers claiming to know how to fix the WordPress database connection problem and never find this issue. Without detailed error messages you would be flailing around for days before giving up completely.

Problem 2: Bad host name or DNS lookup issue

Warning: mysqli_real_connect(): (HY000/2002): php_network_getaddresses: getaddrinfo failed: No such host is known. 
in D:\rundle\WordPress\wordpress-5.5.3\wordpress\wp-includes\wp-db.php on line 1635
php_network_getaddresses: getaddrinfo failed: No such host is known.

This means the DNS lookup failed for the hostname you have provided. This might be because the hostname is misspelled or it might mean the DNS server that your site uses has no entry for the host. Fixing a spelling error is easy. The other problem is harder but at least you can talk intelligently about it to people that know how to fix DNS lookup problems.

Check the spelling error in wp-config.php….

/** MySQL hostname */
define( 'DB_HOST', 'localhost' );

Problem 3: Database not running or not accessible

Warning: mysqli_real_connect(): (HY000/2002): No connection could be made because the target machine actively refused it. 
in D:\rundle\WordPress\wordpress-5.5.3\wordpress\wp-includes\wp-db.php on line 1635
No connection could be made because the target machine actively refused it.

This means that your database is not reachable. It might not be running. There might be a firewall issue. The default port might have been changed. There are a lot of things to look into, but the problem has been narrowed considerably.

Problem 4: Invalid user name

Warning: mysqli_real_connect(): (HY000/2054): The server requested authentication method unknown to the client 
in D:\rundle\WordPress\wordpress-5.5.3\wordpress\wp-includes\wp-db.php on line 1635
The server requested authentication method unknown to the client

This cryptic message means the user is not defined. With any set of credentials, WordPress will try a few authentication methods before giving up. WordPress assumes the credentials are valid, but simply doesn't have the proper authentication method defined.

Check the user name in wp-config.php…

/** MySQL database username */
define( 'DB_USER', 'username_here' );

Problem 5: Invalid password

Warning: mysqli_real_connect(): (HY000/1045): Access denied for user 'wpuser'@'localhost' (using password: YES) 
in D:\rundle\WordPress\wordpress-5.5.3\wordpress\wp-includes\wp-db.php on line 1635
Access denied for user 'wpuser'@'localhost' (using password: YES)

Your password for the MySQL database is wrong. In this case the username is wpuser. Check the password in wp-config.php…

/** MySQL database password */
define( 'DB_PASSWORD', 'password_here' );

Problem 6: Database name wrong or database does not exist or user does not have access

Access denied for user 'wpuser'@'localhost' to database 'wpbench2'

This means that the database name is wrong or does not exist. WordPress can create the database tables from an empty database but it cannot create the database itself.

Check the database name in wp-config.php…

// ** MySQL settings - You can get this info from your web host ** //
/** The name of the database for WordPress */
define( 'DB_NAME', 'wpbench2 );

If the name is right, then you need to log in to the database using a tool like MySQL Bench to see if the schema exists.

If the schema exists then the next issue to determine is if your database user has access to the schema.

With all schema privileges, the WordPress site will be able to create all the tables from an empty schema. It is not good practice to allow all privileges to the database user, however if the database is initially empty then you will need more privileges then if the schema is properly initialized. Determining the minimum set of privileges required is a topic for another post.

Finally…

So once you get your site working and go from 😭 to 😎 it is easy to simply forget everything and move on. But wait! Before you do that you need to turn off diagnostics…

In wp-config.php, change…

define( 'WP_DEBUG', true );

back to

define( 'WP_DEBUG', false );

There is a reason that WordPress does not, by default, give you detailed error messages. It is because the error messages can display sensitive information such as server names and user names which can be used to compromise your system.

So after getting your connection to work…turn the idiot light back on!