"Error Establishing a Database Connection" in WordPress — The Real Fix Guide

A white screen with one sentence — "Error establishing a database connection." — and the whole site is gone: front-end, wp-admin, everything. Ninety percent of the time it's one of four things: wrong credentials in wp-config.php, a MySQL service that crashed, a corrupted wp_options table, or the host hit a resource limit. Here's how to diagnose which one in under 10 minutes, then fix it.

mysite.com

⚠ Error establishing a database connection

This either means that the username and password information in your wp-config.php file is incorrect, or that contact with the database server at localhost could not be established.

WordPress 6.8 · PHP 8.2 · DB_HOST: localhost · DB_USER: wp_user

My Blog

HomeAboutContact

✓ Connection restored · wp-config patched

Latest Posts

Comment×

Fix DB credentials in wp-config.php|

Fix it ⟳ ✓ Done

SimpleReview PRO

waiting for selection…

Detected

ErrorDB connect fail

Filewp-config.php

Fix plan

Update DB_PASSWORD to match cPanel value · ping localhost to confirm MySQL up

Result

mysqli_connect OK. Front-end and wp-admin restored.

✓ PR opened

fix: update DB_PASSWORD in wp-config.php
wp-config.php · 1 line

Click SimpleReview → select the DB error → Fix it → wp-config patched, site back online

What the Error Actually Means

WordPress renders every page by making a mysqli_connect() call to your database. If that call returns false, PHP gets no data, so WP throws the generic error screen:

Error establishing a database connection

This either means that the username and password information in your
wp-config.php file is incorrect or that contact with the database server
at localhost could not be established. This could mean your host's
database server is down.

The WordPress message itself doesn't tell you which of the four failure modes happened. To figure that out you need one debug line in wp-config.php:

define( 'WP_DEBUG',         true );
define( 'WP_DEBUG_LOG',     true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Reload the site, then open wp-content/debug.log. The real PHP error appears there — for example:

PHP Warning: mysqli_real_connect(): (HY000/1045):
  Access denied for user 'wp_user'@'localhost' (using password: YES)
  in /wp-includes/class-wpdb.php on line 1987

PHP Warning: mysqli_real_connect(): (HY000/2002):
  No such file or directory in /wp-includes/class-wpdb.php on line 1987

PHP Warning: mysqli_real_connect(): (HY000/1040):
  Too many connections in /wp-includes/class-wpdb.php on line 1987

Each error code maps to a different root cause:

Step 1: Verify Credentials in wp-config.php

This is the highest-probability fix. Connect via SFTP or your host's File Manager and open wp-config.php at the site root. You're looking for these four lines:

define( 'DB_NAME',     'my_wp_db' );
define( 'DB_USER',     'wp_user' );
define( 'DB_PASSWORD', 'KhUj9!sQp2z...' );
define( 'DB_HOST',     'localhost' );

Now cross-check each value against your hosting control panel:

• cPanel: MySQL Databases → compare DB name + username. Click "Add User to Database" to reset the password if you don't remember it.
• Managed hosts (SiteGround, Kinsta, WP Engine, Cloudways): Sites → Database → show credentials.
• AWS / DigitalOcean / VPS: check your provisioning script or mysql -u root -p then SELECT user, host FROM mysql.user;

Test the credentials without WordPress

Upload a tiny test file next to wp-config.php called db-test.php:

<?php
$link = mysqli_connect('localhost', 'wp_user', 'YOUR_PASSWORD', 'my_wp_db');
if (!$link) {
  echo 'FAIL: ' . mysqli_connect_error();
} else {
  echo 'OK — connected to ' . mysqli_get_host_info($link);
}

Visit yoursite.com/db-test.php. If this returns "OK" but WordPress still errors, the problem isn't credentials — skip to Step 3. If this returns FAIL: Access denied, you've confirmed the password is wrong. Delete db-test.php when you're done.

Step 2: Is MySQL Actually Running?

If MySQL itself crashed, no credentials will help. SSH into the server and check:

# Debian / Ubuntu
sudo systemctl status mysql
sudo systemctl restart mysql

# CentOS / RHEL / AlmaLinux
sudo systemctl status mariadb
sudo systemctl restart mariadb

# Check error log for the crash reason
sudo tail -n 100 /var/log/mysql/error.log

Common crash causes: out of memory (OOM killer logged in dmesg), corrupted InnoDB redo log (need innodb_force_recovery = 1 in my.cnf), or a stuck table lock. On shared hosting you can't restart the service — open a support ticket quoting the MySQL error code you found in debug.log.

Check disk space

A full disk silently kills MySQL writes. Run:

df -h
du -sh /var/lib/mysql/*

If any partition is at 100%, free space (clear old logs in /var/log/, old backups, /tmp/) then restart MySQL.

Step 3: Repair Corrupted Tables

If the front-end shows the generic DB error but /wp-admin/ shows a different message — "One or more database tables are unavailable" — that's a corrupted-table signature. Usually wp_options (after a plugin deactivation interruption) or wp_postmeta (after a disk-full write).

Method A: Built-in WordPress repair

Add this line to wp-config.php (anywhere above the "That's all, stop editing" marker):

define( 'WP_ALLOW_REPAIR', true );

Visit https://yoursite.com/wp-admin/maint/repair.php. Click Repair Database (safe) or Repair and Optimize Database (slower, defragments too). Remove that line when done — the repair page is public and doesn't require login.

Method B: WP-CLI (faster, safer)

If you have SSH access and WP-CLI installed:

# Check all tables for corruption
wp db check

# Repair corrupted tables
wp db repair

# Optimize after repair
wp db optimize

# Nuclear option: dump, drop, recreate, import
wp db export backup.sql
wp db reset --yes
wp db import backup.sql

Method C: Direct MySQL

mysql -u root -p my_wp_db
mysql> CHECK TABLE wp_options;
mysql> REPAIR TABLE wp_options;
mysql> REPAIR TABLE wp_postmeta;

Step 4: Host Resource Limits

On shared hosting, DB errors that appear only during traffic spikes usually mean you hit the max_connections limit (often set to 15-30 on cheap plans). Signs:

• Error appears intermittently, not constantly.
• debug.log shows MySQL error 1040: Too many connections.
• Site recovers on its own after 30-60 seconds.

Fixes, in order of cost:

1. Install a cache plugin (WP Rocket, LiteSpeed Cache, W3 Total Cache). Static HTML pages don't hit MySQL — this often fixes 90% of the spikes.
2. Disable heavy plugins that fire queries on every page load (related-posts plugins, visitor counters, admin-ajax abuse).
3. Kill bad bots. Add aggressive crawlers to robots.txt or block by user-agent in nginx/.htaccess. AhrefsBot, SemrushBot, and scraper farms can easily exhaust connections.
4. Upgrade the plan. Shared → VPS or managed WordPress host with proper DB tuning.

Step 5: After a Migration

Migrations are the classic cause of this error. Anyone who just moved a site from one host to another and sees "Error establishing a database connection" should:

1. Update DB_NAME, DB_USER, DB_PASSWORD, DB_HOST in wp-config.php to the new host's values.
2. Confirm the SQL dump actually imported — SHOW TABLES FROM my_wp_db; should list wp_posts, wp_options, etc.
3. If the new host uses a non-standard DB_HOST (DreamHost, RDS, Hostinger, some SiteGround setups), use the exact value from the host's knowledge base — not "localhost".
4. Once connected, run wp search-replace 'https://oldsite.com' 'https://newsite.com' to fix siteurl and post URLs.

When to Hand It Off to AI

Manual debugging works, but requires SSH, patience, and a tolerance for MySQL error codes. SimpleReview (Chrome extension or WordPress plugin) automates the whole triage:

1. Install the extension and open the broken site. The DB-error screen loads — that's fine, SimpleReview doesn't need the site to work.
2. Click the SimpleReview icon, then click the error text.
3. Type "Fix DB connection" and click Fix it.
4. SimpleReview reads wp-config.php over SFTP, compares credentials against your hosting API (when available), tests mysqli_connect, inspects disk + max_connections, and opens a PR with the one-line fix — usually an updated DB_PASSWORD or a corrected DB_HOST.

Useful when you're on mobile, in a client meeting, or just don't feel like SSHing into a production server at 2 AM.

Frequently Asked Questions

Related WordPress Fixes

Sources

• wordpress.org — Handling the DB connection error
• wordpress.org — Editing wp-config.php
• developer.wordpress.org — WP-CLI db commands
• dev.mysql.com — MySQL error code reference
• wordpress.org — Debugging in WordPress (WP_DEBUG_LOG)