Fix “Error Establishing a Database Connection” in WordPress

Overview

The Error Establishing a Database Connection is one of the most disruptive errors in WordPress. It takes down your entire site — front end and wp-admin — and gives you almost no information about what actually went wrong. That’s what makes it frustrating.

At its core, the error means WordPress tried to connect to MySQL and failed. That could be wrong credentials in wp-config.php, a crashed MySQL service, a corrupted database, or a misconfigured hostname. Each cause has a different fix, so the goal is to work through them in order — fastest to diagnose first.

This article is written for WordPress sites on shared hosting, VPS, and dedicated servers. Some steps require SSH or cPanel access. If you’re on our Managed WordPress Hosting, open a support ticket instead — we handle MySQL-level issues on your behalf.

Prerequisites

• FTP, SFTP, or File Manager access to your WordPress root directory
• cPanel, Plesk, or WHM access (for checking MySQL databases and users)
• SSH access (recommended for faster diagnosis — not required for all steps)
• Your current wp-config.php database credentials (or access to retrieve them)
• WordPress 5.x or later (steps are the same for 6.x)

Step-by-Step Instructions

Step 1: Check Whether wp-admin Is Also Down

Visit https://yourdomain.com/wp-admin directly. If you see the same error there, the problem is a genuine database connectivity issue — not a theme or plugin problem on the front end only. If wp-admin loads but the front end doesn’t, skip to the troubleshooting section and look at the corrupted database table issue.

Step 2: Verify Your Database Credentials in wp-config.php

Wrong credentials are the most common cause, especially after a site migration or a hosting account change. Open your wp-config.php file — it’s in the root of your WordPress installation, typically /home/username/public_html/wp-config.php on cPanel hosts.

Look for these four lines:

define( 'DB_NAME', 'your_database_name' );
define( 'DB_USER', 'your_database_user' );
define( 'DB_PASSWORD', 'your_database_password' );
define( 'DB_HOST', 'localhost' );

Now cross-reference each value against your actual MySQL database in cPanel:

1. Log in to cPanel and go to MySQL Databases.
2. Under Current Databases, confirm the database name matches DB_NAME exactly — including any cPanel username prefix (e.g. htuser_wpdb).
3. Under Current Users, confirm the username matches DB_USER.
4. Click Check Password next to the user to verify the password in wp-config.php is correct. If it’s wrong, update it here or update wp-config.php to match.
5. Confirm the user is assigned to the database under Add User to Database — assigned with All Privileges.

📝 Note: On WHM-managed servers, database usernames are prefixed with the cPanel account name. If you migrated from a server without that prefix, this is almost certainly your problem.

Step 3: Test the DB_HOST Value

localhost works on most shared hosting and single-server VPS setups. But there are cases where it won’t:

• Some hosts require a socket path instead of a hostname
• If MySQL is running on a separate database server (common on VPS clusters or dedicated setups), DB_HOST needs to be the internal IP or hostname of that server
• Non-standard MySQL ports need to be specified as localhost:3308 (or whatever port applies)

Check your hosting welcome email or control panel for the correct database host value if localhost isn’t working.

Step 4: Check Whether MySQL Is Actually Running

If credentials are correct and the host value is right, MySQL itself may be down. This happens after server crashes, resource exhaustion, or failed updates.

Via SSH, run:

sudo systemctl status mysql
# or on servers using MariaDB:
sudo systemctl status mariadb

If the service is stopped or failed, restart it:

sudo systemctl restart mysql
# or:
sudo systemctl restart mariadb

⚠ Warning: If MySQL crashes repeatedly within minutes of restarting, don’t keep restarting it. Check /var/log/mysql/error.log for the actual reason. A common culprit is the server running out of memory — on a VPS, this usually means you’ve outgrown your current plan.

If you don’t have SSH access, log in to WHM and go to Restart Services > SQL Server (MySQL).

Step 5: Run the WordPress Database Repair Tool

If MySQL is running but the connection still fails — or if wp-admin throws a “One or more database tables are unavailable” error — one or more tables may be corrupted.

Enable the repair tool by adding this line to wp-config.php, just before the /* That's all, stop editing! */ line:

define( 'WP_ALLOW_REPAIR', true );

Then visit:

https://yourdomain.com/wp-admin/maint/repair.php

Click Repair and Optimize Database. Once it finishes, remove the WP_ALLOW_REPAIR line from wp-config.php immediately.

⚠ Warning: Leave WP_ALLOW_REPAIR enabled and anyone can run the repair tool against your database without logging in. Remove it as soon as you’re done.

Step 6: Check File Permissions on wp-config.php

This one gets overlooked. If wp-config.php has incorrect permissions, PHP can’t read it and the database credentials never get passed to WordPress.

The correct permission is 640 or 644. Via SSH:

ls -la /home/username/public_html/wp-config.php
chmod 640 /home/username/public_html/wp-config.php

📝 Note: Some security guides recommend 400 (owner read-only). That’s fine as long as PHP runs as the file owner, which is the case on most cPanel setups using suPHP or suEXEC. On servers where PHP runs as www-data or apache, you may need 644.

Common Issues & Troubleshooting

Correct Credentials but Still Getting the Error

The credentials in wp-config.php match the database panel exactly, but the error persists. Nine times out of ten, the MySQL user hasn’t actually been granted privileges on that database. In cPanel, go to MySQL Databases, scroll to Add User to Database, select the user and database, and grant All Privileges. This step is separate from creating the user and is frequently skipped during manual setups.

Error Only Appears Intermittently

If the site loads fine sometimes and throws the error other times, the database is likely hitting its connection limit. This is common on shared hosting plans with high-traffic WordPress sites, or on VPS instances where the max_connections value in MySQL is set too low. Check /etc/mysql/my.cnf or /etc/my.cnf for the max_connections setting. A persistent fix usually means either optimising queries (a caching plugin like WP Super Cache helps) or upgrading your hosting plan.

wp-admin Loads but Frontend Shows the Error

This is almost always a corrupted wp_options table rather than a true connection failure. Run the repair tool in Step 5 above. If that doesn’t clear it, connect to the database directly via phpMyAdmin and check the wp_options table for obvious corruption or missing rows for siteurl and home.

Error After Migrating WordPress to a New Host

Migrations are the number one trigger for this error. The database name and username on the new server almost certainly differ from the old one — especially if you’ve moved to a cPanel environment that prepends the account username. Update wp-config.php with the new values. Also double-check that the database was actually imported; it’s easy to move the files without importing the .sql dump.

MySQL Service Keeps Crashing

Look at /var/log/mysql/error.log — don’t guess. Common causes include the InnoDB buffer pool being set too high for available RAM, a full disk partition (df -h will show this immediately), or a corrupted InnoDB tablespace. If the disk is full, that’s your answer. If it’s a memory issue and you’re on a VPS, I’d recommend reviewing your MySQL configuration or considering a plan with more RAM before the crashes start causing data loss.

FAQ