WordPress Database Connection Error: Complete Fix Guide
"Error establishing a database connection" is one of the most common — and most alarming — WordPress errors. It appears as a plain white page with a single sentence, replacing your entire site. The message is blunt because WordPress cannot generate any page without first querying the database for posts, settings, and theme data. When that query fails, there is nothing left to render.
The error means WordPress tried to open a connection to MySQL (or MariaDB) and was rejected or ignored. The cause is almost always one of six things: wrong credentials in wp-config.php, the database server is down, the database user lacks privileges, the server is out of resources, the database is corrupted, or the wp-config.php file itself was damaged. The steps below walk through each cause in order of likelihood.
Step 1: Check wp-config.php Credentials
The first place to look is wp-config.php in your WordPress root directory. WordPress uses four constants to connect to the database:
define('DB_NAME', 'wordpress_db');
define('DB_USER', 'wp_user');
define('DB_PASSWORD', 'your_password');
define('DB_HOST', 'localhost');Verify each value against what your hosting panel or database server expects. Common mistakes: a recent password change that was not updated here, a typo after a manual edit, or DB_HOST set to localhost when the database lives on a separate server (in which case it should be an IP or hostname like db.internal.example.com). If you recently migrated the site, the credentials almost certainly changed.
Step 2: Verify MySQL or MariaDB Is Running
If the credentials are correct, the database server itself may be down. Check the service:
# MySQL
sudo systemctl status mysql
# MariaDB
sudo systemctl status mariadbIf it shows inactive or failed, start it:
sudo systemctl start mysqlA database that repeatedly crashes is usually starved for memory — the OOM killer terminates mysqld when the server runs out of RAM. Check the logs:
journalctl -u mysql -n 50 --no-pager
dmesg -T | grep -i "oom"Step 3: Test the Database Connection Manually
Isolate whether the problem is WordPress or the database by connecting with the mysql client using the exact credentials from wp-config.php:
mysql -u wp_user -p wordpress_dbEnter the password when prompted. If you get ERROR 1045 (28000): Access denied, the credentials or privileges are wrong. If you get ERROR 2002 (HY000): Can't connect to local MySQL server, the server is not running or the socket path is wrong. A successful login means the database is fine and the issue is in wp-config.php or a WordPress plugin.
If access is denied, grant the user privileges:
GRANT ALL PRIVILEGES ON wordpress_db.* TO 'wp_user'@'localhost';
FLUSH PRIVILEGES;Step 4: Check Database Server Resources
A database server that is technically running but starved will refuse new connections. WordPress hits max_connections and surfaces the same "Error establishing a database connection" page. Check the basics:
# Disk space — a full disk stops MySQL from writing
df -h
# Memory
free -h
# Current connection count vs. limit
mysql -u root -p -e "SHOW STATUS LIKE 'Threads_connected'; SHOW VARIABLES LIKE 'max_connections';"If Threads_connected is near max_connections, either raise the limit or find what is leaking connections (often a badly written plugin). A full disk is especially common on cheap VPS plans where log files or backups fill the partition. To raise the connection limit temporarily:
SET GLOBAL max_connections = 200;To make the change permanent, add the line max_connections = 200 to your my.cnf (or mysqld.cnf) under the [mysqld] section and restart the database. Keep in mind that raising the ceiling only buys time: if a plugin opens a new connection on every request without closing it, the leak will eventually hit any limit. Use SHOW PROCESSLIST to see which queries are holding connections open, and disable plugins one by one until the culprit reveals itself.
Step 5: Repair a Corrupted Database
Sometimes the connection succeeds but the tables are damaged — usually after a server crash mid-write. WordPress has a built-in repair script. Add this line to wp-config.php:
define('WP_ALLOW_REPAIR', true);Then visit https://example.com/wp-admin/maint/repair.php in your browser. You can choose "Repair Database" or "Repair and Optimize Database." No login is required for this page, so remove the WP_ALLOW_REPAIR line from wp-config.php once you are done. Alternatively, repair tables via the command line:
USE wordpress_db;
REPAIR TABLE wp_posts, wp_options, wp_postmeta;Or through phpMyAdmin: select the database, check all tables, and choose "Repair table" from the dropdown.
Step 6: Check for a Corrupted wp-config.php File
If nothing else works, the wp-config.php file itself may be corrupted — a partial FTP upload, an encoding change (a BOM added by a Windows editor), or an accidental edit that introduced a syntax error. Restore it from a known-good backup. If you have no backup, regenerate the essential constants using fresh salt keys from the WordPress API together with your database details:
# Fetch fresh authentication salts
curl -s https://api.wordpress.org/secret-key/1.1/salt/Replace the AUTH_KEY through NONCE_SALT block in wp-config.php with the fresh output, confirm the file has no BOM, and reload the site. A BOM at the start of the file causes PHP to send headers before WordPress runs, producing "headers already sent" errors that can cascade into database connection failures.
Quick Reference: Causes and Fixes
| Symptom / Log Message | Root Cause | Fix |
|---|---|---|
| Access denied for user | Wrong DB_USER or DB_PASSWORD | Correct credentials in wp-config.php |
| Can't connect to MySQL server | Database service stopped | systemctl start mysql/mariadb |
| Site works, then fails intermittently | max_connections exhausted | Raise limit; find connection leak |
| "One or more database tables are unavailable" | Corrupted tables | Run wp-admin/maint/repair.php |
| Blank page, no error text | Corrupted wp-config.php | Restore from backup; remove BOM |
| Error after migration | DB_HOST or DB_NAME changed | Update wp-config.php for new host |