Home » Database » Error Establishing a Database Connection in WordPress: Fix It

Error Establishing a Database Connection in WordPress: Fix It

Error establishing a database connection means PHP could not log in to MySQL or MariaDB with the details in wp-config.php. WordPress cannot load a single page without its database, so the front end and wp-admin both stop working.

It usually shows up after a migration, a password change in the hosting panel, a full disk, or a database server that crashed under load. The cause is almost always one of four things: wrong credentials, wrong host, a stopped database server, or damaged tables.

I work through them in that order, because each check rules out the next one.


On the front end WordPress keeps the message short. Open /wp-admin/ instead: in the admin WordPress prints the full message, which names the database host it tried and asks whether the username and password are correct.

If the admin shows One or more database tables are unavailable instead, the login worked and the problem is damaged tables. Skip ahead to Step 6.

You are going to edit the file that holds your database password, so make a copy first. Over SSH:

cd /path/to/wordpress
cp wp-config.php wp-config.php.bak

No output means it worked. In a file manager, download the file to your computer before you touch it.

Print the lines WordPress uses to connect:

grep -E "DB_(NAME|USER|PASSWORD|HOST)" wp-config.php

You should see four define() lines. Compare each value with what your hosting panel lists for the database. Look closely at the details that break things quietly: a missing account prefix on shared hosting (user_wp123 versus wp123), a password with a stray space, or a quote character that ended up inside the value.

💡 If the password contains a $ and you wrapped it in double quotes, PHP treats it as a variable. Use single quotes around the value.

This step tells you exactly what is wrong instead of guessing. Use the values from Step 2:

mysql -u DB_USER -p -h DB_HOST DB_NAME

Type the password when asked. If you get a mysql> prompt, the credentials are fine and the problem is in how WordPress reaches the server (go to Step 5). If you get an error, it points to the cause:

  • Access denied for user: wrong username or password, or the user has no rights on that database. Go to Step 4.
  • Unknown database: DB_NAME is wrong, or the database was never created or imported after a migration.
  • Can't connect to local MySQL server through socket or Can't connect to MySQL server: the server is down or the host is wrong. Go to Step 5.

If you have WP-CLI, wp db check runs a similar test with the credentials from wp-config.php. It calls mysqlcheck and ends with Success: Database checked. when the login works.


When the login is denied, do not keep guessing the old password. Set a new one and write it into wp-config.php.

On a VPS, log in to MySQL as root and run this:

mysql -u root -p

ALTER USER 'wp_user'@'localhost' IDENTIFIED BY 'new-strong-password';
GRANT ALL PRIVILEGES ON wp_database.* TO 'wp_user'@'localhost';
FLUSH PRIVILEGES;

Then put the same password in DB_PASSWORD. The 'localhost' part must match where the user connects from. A user created for 'localhost' is a different account from one created for '%' or a remote IP.

On shared hosting, do the same in the panel: reset the database user’s password and make sure the user is added to the database with all privileges. A user that exists but is not attached to the database gets Access denied too.

In OpenPanel that is MySQL > Users, where you reset the password, and the user has to be assigned to the database before it can connect, the same idea as “Add User To Database” in cPanel. The Database Wizard creates the database, the user and the assignment in one go. One difference to watch: the OpenPanel database docs say PHP apps like WordPress should use localhost as DB_HOST with no port, and never 127.0.0.1.

localhost works on most hosts, but not all. Some managed hosts use a separate database hostname, and some servers run MySQL on another port or a non-default socket. These are the formats DB_HOST accepts:

// Default
define( 'DB_HOST', 'localhost' );

// MySQL on another port
define( 'DB_HOST', '127.0.0.1:3307' );

// Unix socket
define( 'DB_HOST', 'localhost:/var/run/mysqld/mysqld.sock' );

// Separate database server
define( 'DB_HOST', 'mysql.example.com:3307' );
error establishing a database connection wp config 1 - Error Establishing a Database Connection in WordPress: Fix It
Where it goes in wp-config.php: above the “That’s all, stop editing!” line

Use only one of these lines, with the host your provider gives you. The full list is in the wp-config.php documentation.

See also  Adding high-performance keys to MySQL tables to speed up WordPress 🧑🏿‍🚀

If the host is right and the connection is still refused, check that the database server is running at all:

systemctl status mysql
# or, on MariaDB
systemctl status mariadb

It should say active (running). If it says failed or inactive, look at why before you restart it:

journalctl -u mysql -n 50 --no-pager
df -h

A full disk is a common reason MySQL refuses to start or stops mid-write. If df -h shows a partition at 100%, free space first (this is how I find what fills the disk), then run systemctl start mysql. If the server keeps dying under traffic, check the log for out-of-memory kills.

If the site works for a while and only fails under load, you may be hitting a connection limit instead. That has its own message and fix: User already has more than max_user_connections active connections.


If the login works but WordPress still fails, or you saw One or more database tables are unavailable, check the tables. Export a backup first with wp db export, then:

wp db check
wp db repair

wp db repair runs mysqlcheck with --repair and prints Success: Database repaired. when it finishes.

Without shell access, use the built-in repair page. Add this line to wp-config.php above the “stop editing” comment:

define( 'WP_ALLOW_REPAIR', true );
error establishing a database connection wp config 2 - Error Establishing a Database Connection in WordPress: Fix It
Where it goes in wp-config.php: above the “That’s all, stop editing!” line

Then open https://example.com/wp-admin/maint/repair.php and click Repair Database. Anyone can open that page while the constant is set, so, as the docs say, remove the line again once the issue is solved.

If one table keeps coming back as crashed, usually wp_options, follow wp_options is marked as crashed and should be repaired.


When the connection fails, WordPress looks for a wp-content/db-error.php drop-in and loads it instead of the default message. That lets you show visitors a plain “back in a few minutes” page and tell search engines the outage is temporary:

<?php
// wp-content/db-error.php
http_response_code( 503 );
header( 'Retry-After: 600' );
?>
<!DOCTYPE html>
<html><head><meta charset="utf-8"><title>Back soon</title></head>
<body><h1>We are having a short technical problem.</h1>
<p>Please try again in a few minutes.</p></body></html>

💡 Keep the drop-in plain HTML. The database is down when this file runs, so anything that needs it will fail.

To keep the error from coming back, put an uptime monitor on the site so you hear about a stopped database before your visitors do, keep free disk space on the server, and update DB_PASSWORD whenever someone changes the database password in the panel. After a migration, run the mysql test from Step 3 before you switch DNS.

TL;DR: back up wp-config.php, test the DB_USER and DB_PASSWORD login with the mysql client, reset the password if access is denied, fix DB_HOST or start the database server if it cannot connect, and run wp db repair or WP_ALLOW_REPAIR if the tables are damaged.

Was this post helpful?

Leave a Comment

I enjoy constructive responses and professional comments to my posts, and invite anyone to comment or link to my site.

Recommended