Key Takeaways
- When WordPress can’t connect to its MySQL database, it shows this message. It can happen for a number of reasons, including incorrect login information or a crashed MySQL service.
- Checking wp-config.php is always the quickest first step because most problems are caused by wrong DB_NAME, DB_USER, DB_PASSWORD, or DB_HOST values.
- If you see “database tables unavailable” in wp-admin instead of the usual error, it means that the tables are corrupt. Don’t use credential fixes; use the built-in repair tool or WP-CLI.
- When errors happen only sometimes when there is a lot of traffic, it usually means that the maximum number of connections has been reached. Without changing any code, vertical scaling on Cloudways fixes this.
- Before making any changes to wp-config.php, running DB repair, or restarting MySQL services, always make a backup.
You open your website. You don’t get a homepage; instead, you get a blank white screen with the message “Error establishing a database connection” Not a stack trace or a line number. That’s all. You’re losing traffic, sales, and money every second it stays up.
The good news is that this error has a set of known causes, and each one has a clear solution. This guide goes through all of them in the order that they are most likely to happen, starting with the most common one (a mismatch in wp-config.php credentials) and ending with server-level problems like a crashed MySQL service or a full connection pool.
-
- What Does “Error Establishing a Database Connection” Mean?
- Before You Begin: Back Up Your Site
- How to Diagnose the Error First
- Fix 1: Check Your Database Credentials in wp-config.php
- Fix 2: Correct the Database Host Value (DB_HOST)
- Fix 3: Reset or Resync Your Database Password
- Fix 4: Repair a Corrupted WordPress Database
- Fix 5: Check if the MySQL Service Is Running
- Fix 6: Check for Max Connection Limit Issues
- Fix 7: Deactivate Plugins and Switch to a Default Theme
- Still Getting the Error? Enable WordPress Debug Mode
- Frequently Asked Questions
What Does “Error Establishing a Database Connection” Mean?
WordPress is not like an unmoving painting. WordPress uses PHP to send a request to a MySQL database every time a visitor loads a page. It then gets the page content, puts together the response, and sends it to the browser. This is what that sequence looks like:
When the PHP-to-MySQL handshake fails completely, the “Error Establishing a Database Connection” message appears. WordPress can’t fetch anything, so instead of a page, visitors see an error. The whole site goes down because the failure is at the connection level, not the content level. This includes the frontend, wp-admin, REST API, and everything else.
There’s one important exception. If wp-admin loads but shows “One or more database tables are unavailable. The database may need to be repaired” instead of the standard error, the MySQL service is still reachable, but one or more tables inside the database are corrupted. That’s a different problem with a different fix, covered in Fix 4.
The most common root causes of the full connection error are:
- Incorrect database credentials in wp-config.php (DB_NAME, DB_USER, DB_PASSWORD, or DB_HOST)
- A wrong or non-standard DB_HOST value
- The MySQL service crashed or was restarted on the server
- The server hit its maximum allowed database connections under traffic load
- A plugin or theme is holding open connections or sending malformed queries
- Corrupted database tables (produces the variant error in wp-admin only)
Each of these maps to a specific fix below. Work through them in order. Most sites resolve at Fix 1 or Fix 2.
Before You Begin: Back Up Your Site
Before touching wp-config.php, running a database repair, or restarting any service, take a backup. If something goes wrong mid-fix, a recent backup is the difference between a five-minute restore and a multi-hour rebuild.
On Cloudways, go to Servers → [your server] → Backups. Click Take Backup Now to trigger an on-demand backup. If Local Backups are enabled, this also creates a downloadable copy of all applications on the server.
How to Diagnose the Error First
Before jumping into fixes, spend 30 seconds narrowing the problem down. The behavior difference between your frontend and wp-admin tells you exactly which category of fix applies.
Same Error on Both Frontend and wp-admin
If both yourdomain.com and yourdomain.com/wp-admin/ return the “Error Establishing a Database Connection” message, the database connection itself is broken. Work through Fix 1, Fix 2, Fix 3, and Fix 5 in order.
wp-admin Shows “Database Tables Unavailable” Instead
If your frontend returns the connection error but wp-admin loads (even partially) and displays “One or more database tables are unavailable. The database may need to be repaired,” the MySQL connection itself is working, but the problem is table-level corruption. Skip to Fix 4.
Fix 1: Check Your Database Credentials in wp-config.php
This is the most common reason. WordPress keeps the information it needs to connect to its database in the file wp-config.php. If any of the four important values are wrong, even by one character, the connection will not work at all. This happens when you move your hosting, change your password, or switch platforms and update the database credentials but not wp-config.php.
How to Locate wp-config.php
Connect to your server via SFTP using a client like FileZilla. The wp-config.php file lives in your application’s root directory, inside the public_html folder.
Alternatively, connect via SSH and open the file directly:
Right-click the file in FileZilla and open it with a plain-text editor (VS Code, Sublime Text, or Notepad++ all work). Avoid word processors like Microsoft Word, as they add invisible formatting characters that corrupt PHP files.
The Four Values to Verify
Inside wp-config.php, locate this block:
define( ‘DB_NAME’, ‘database_name_here’ );/** MySQL database username */
define( ‘DB_USER’, ‘username_here’ );/** MySQL database password */
define( ‘DB_PASSWORD’, ‘password_here’ );/** MySQL hostname */
define( ‘DB_HOST’, ‘localhost’ );
Each value must exactly match what your hosting platform has on record. Note down all four before comparing them against your actual credentials in the next step.
Where to Find Your Correct Credentials on Cloudways
In the Cloudways platform, go to Applications → [your WordPress app] → Access Details. Scroll to the MySQL Access section. You’ll see the actual DB Name, Username, and Password for your application.
Compare these values character-by-character against what’s in your wp-config.php. If anything doesn’t match, update wp-config.php to reflect the correct values and save the file.
Verify via the Database Manager (wp_options Check)
For a secondary verification, click Launch Database Manager from the same Access Details panel.
In the Database Manager, choose your WordPress database and open the wp_options table. The first two rows, siteurl and home, should match the domain name you actually use. If they show a different URL, like a staging domain, an old domain, or a localhost address, it means that the credentials are connecting to the wrong database.
Reload your site if the siteurl and home values are correct and the wp-config.php credentials now match the MySQL Access panel. For most people, this fixes the problem.
Fix 2: Correct the Database Host Value (DB_HOST)
The DB_HOST value tells WordPress where the MySQL server is. Most of the time, this is localhost, which means that the database server and the web server are on the same computer. But some hosting setups use a different address, and if you use the wrong one, the connection will break even if the credentials are correct.
Some common alternatives to localhost are:
- 127.0.0.1: is the loopback IP. It works like localhost but goes straight to TCP instead of going through the socket. If localhost is taking too long, try this.
- mysql.yourdomain.com or an internal server address, which is used when MySQL is on a different server (which is common in some managed hosting setups).
- Some Linux setups use a Unix socket to connect to MySQL, which is why you might see a socket path like localhost:/var/run/mysqld/mysqld.sock.
For almost all standard WordPress apps on Cloudways, localhost is the right value. Set this back to localhost first if you’ve changed it to something else or gotten a wp-config.php file from another host.
If you’re on a different host and unsure of the correct value, WordPress maintains an official reference list of DB_HOST values by hosting provider. You can also contact your host’s support team and ask for the exact MySQL hostname.
Fix 3: Reset or Resync Your Database Password
If Fix 1 told you that your credentials were wrong but you don’t know what the right password is, or if you changed it recently on your hosting platform and forgot to update wp-config.php, here’s how to get them back in sync.
Always make sure that wp-config.php is up to date with your hosting platform, not the other way around. If you change the MySQL password on your hosting platform while the site is live, it will break the connection for any sessions that are already open.
The right order is:
- To see the current password, go to Access Details > MySQL Access in Cloudways and click the eye icon.
- Use SFTP or SSH to open wp-config.php.
- Make sure the DB_PASSWORD value is exactly the same, including any capital letters and special characters.
- Save the file and test the site.
If the password genuinely needs to be reset (for example, you’ve lost access to the current one), you can update it in Cloudways via Access Details → MySQL Access → Password → edit icon. After saving the new password in Cloudways, update wp-config.php immediately with that same new value.
⚠️ Note: Special characters in passwords (such as @, #, $, or !) sometimes cause issues in wp-config.php if the password string isn’t wrapped in single quotes correctly. If your password contains special characters and the error persists after updating, try wrapping the password value in single quotes:
Managed WordPress Hosting That Keeps Your Database Running
Cloudways handles server management, automated backups, and one-click database access, so database errors are easier to diagnose and faster to fix. Try it free for 3 days.
Fix 4: Repair a Corrupted WordPress Database
If your frontend shows the usual connection error but wp-admin loads and says, “One or more database tables are unavailable,” If you see “The database may need to be repaired,” it means that the tables are corrupted and not that the connection is broken. After an unexpected server shutdown, a failed plugin update, or a disk I/O error while writing, a table can become corrupted.
You can fix the database using either WordPress’s built-in repair tool (which doesn’t need SSH) or WP-CLI (which is faster and gives you more control).
Using WordPress’s Built-In Repair Tool
Open wp-config.php via SFTP (as described in Fix 1) and add the following line anywhere before the /* That’s all, stop editing! */ comment:
Save the file, then navigate to:
https://yourdomain.com/wp-admin/maint/repair.php
You’ll see two options: Repair Database and Repair and Optimize Database. Choose Repair and Optimize Database. It takes longer but is more thorough, checking table structure and reclaiming unused space.
This page is accessible without being logged in, which is a security exposure. Immediately after the repair completes, remove the line you added to wp-config.php and save the file again.
Using WP-CLI to Repair the Database
If you have SSH access (all Cloudways users do by default), WP-CLI is faster and gives you more diagnostic information before committing to a repair.
First, check the database for issues:
This runs mysqlcheck across all tables and lists any that are corrupted or have errors. If issues are found, run the repair:
To also optimize all tables in the same pass:
Run these commands from your application’s root directory (the folder containing wp-config.php). On Cloudways, you can access SSH via Access Details → Application Credentials → SSH Terminal or via any SSH client using the server’s public IP.
wp db check returns a large number of corrupted tables (not just one or two), the corruption may be more extensive than what the repair tool can handle. At that point, restoring from the most recent clean backup is faster and safer than attempting to repair table by table.Fix 5: Check if the MySQL Service Is Running
If your credentials are correct (Fix 1–3 checked out) and you don’t see a message about table corruption in wp-admin, the MySQL service itself may have crashed. This happens when the server restarts for no reason, runs out of memory, or runs out of disk space. The symptom is a full connection error that takes a while to show up. The server is trying to connect to MySQL but is timing out.
On Cloudways
Go to Servers → [your server] → Manage Services. In the services list, locate MySQL and check its status. If it’s stopped or shows an error state, click the restart icon to bring it back up.
If MySQL restarts successfully and the site comes back up, investigate what caused the crash before marking the issue resolved. Common causes include disk space running out (check Servers → Disk Usage) and the server running out of memory under load.
Via SSH
For users comfortable with the command line, connect to your server via SSH and check the MySQL service status directly:
If the output shows Active: inactive (dead) or failed, restart it:
After the restart, tail the MySQL error log to see what caused the crash:
Look for patterns like Out of memory, Table ‘./database/tablename’ is marked as crashed, or InnoDB: Fatal error: cannot allocate memory. Each points to a specific underlying cause.
Fix 6: Check for Max Connection Limit Issues
You can set a limit in MySQL on how many connections it will accept at once. When a WordPress site gets a lot of traffic and reaches its limit, new connection requests start to fail. This causes some visitors to see the database connection error while others can still browse normally.
The main sign is that the error comes and goes, usually when there are spikes in traffic or high-concurrency events like a product launch or a viral post.
You can check the current connection limit and live connection count via SSH:
mysql -u root -p -e “SHOW STATUS LIKE ‘Threads_connected’;”
If Threads_connected is consistently close to or equal to max_connections, you’re hitting the ceiling.
On Cloudways, the fastest resolution is vertical scaling: increasing your server’s RAM and CPU allocation so MySQL can sustain more concurrent connections without additional configuration changes. Go to Servers → [your server] → Vertical Scaling and select a larger server size. Cloudways handles the resize without downtime on most cloud providers.
Alternatively, if you’d prefer to tune MySQL directly, connect via SSH and edit the MySQL configuration file to raise max_connections:
Find or add the line:
Then restart MySQL for the change to take effect. Note that increasing max_connections also increases MySQL’s RAM consumption; each connection uses approximately 1–2 MB. Only raise the limit to a value your server’s available RAM can comfortably support.
Fix 7: Deactivate Plugins and Switch to a Default Theme
A badly written plugin can keep database connections open, run queries in an infinite loop, or make so many queries that the connection pool runs out. This is the most likely reason if the error happened right after you installed or updated a plugin. The same is true, but less often, for themes. You can’t turn off plugins in the WordPress admin because the site is probably down. Instead, use SSH or SFTP.
Deactivate All Plugins via SFTP or SSH
Connect to your server via SFTP (FileZilla) or SSH and navigate to /public_html/wp-content/. Rename the plugins folder to something like plugins_disabled:
mv /path/to/public_html/wp-content/plugins /path/to/public_html/wp-content/plugins_disabled
WordPress won’t be able to find the plugins folder anymore, so it will think that all plugins are turned off. A plugin was to blame if the site loads. Change the name of the folder back to plugins, then go to wp-admin and turn on each plugin one at a time until the error comes back. The last one to turn on is the one that caused the problem.
Switch to a Default Theme via the Database
If disabling plugins didn’t resolve it, the active theme may be responsible. To switch themes without wp-admin access, open the Database Manager in Cloudways ( Access Details → Launch Database Manager ), open the wp_options table, and find the rows where option_name is template and stylesheet. Edit both values to twentytwentyfour (or another default WordPress theme you know is installed). Save and reload the site.
Still Getting the Error? Enable WordPress Debug Mode
If you’ve tried all of the fixes above and the error still happens, WordPress debug mode will show you the specific PHP or MySQL error message that the generic “Error Establishing a Database Connection” screen hides. That code tells you exactly what’s wrong and what you need to look into further.
Open wp-config.php and add these three lines before the /* That’s all, stop editing! */ comment:
define( ‘WP_DEBUG_LOG’, true );
define( ‘WP_DEBUG_DISPLAY’, false );
Setting WP_DEBUG_DISPLAY to false is important. It writes errors to a log file rather than displaying them publicly on-screen. Save the file and load the site, then check the log:
The MySQL error codes you’ll find here have specific meanings:
- ERROR 1045 (Access denied): credentials are wrong. Back to Fix 1 and Fix 3.
- ERROR 2002 (Can’t connect to MySQL server via socket): MySQL is down or using a different socket path. See Fix 5.
- ERROR 2003 (Can’t connect to MySQL server on ‘localhost’): MySQL is not reachable on that host. Check DB_HOST (Fix 2) or MySQL service status (Fix 5).
- ERROR 1040 (Too many connections): max connections exceeded. See Fix 6.
Frequently Asked Questions
What does it mean when WordPress says “Error Establishing a Database Connection”?
A) This error happens when WordPress can’t connect its PHP layer to its MySQL database. WordPress is a content management system (CMS) that changes over time. A live database query is needed to get content every time a page loads. If that connection fails for any reason, such as wrong credentials, a crashed MySQL service, an empty connection pool, or corrupted tables, WordPress can’t show you anything and gives you this error instead of a page.
How do I fix the “Error Establishing a Database Connection” message in WordPress?
A) Go through the possible causes in order of how likely they are to be true. First, compare the four database values in wp-config.php (DB_NAME, DB_USER, DB_PASSWORD, and DB_HOST) to the actual credentials that your hosting platform shows. If those are the same, check that the DB_HOST value is correct for your server. If the credentials are correct, make sure the MySQL service is running. If the error happens sometimes when the system is busy, look into the maximum number of connections. If “tables unavailable” shows up in wp-admin instead of the usual error, use the WordPress database repair tool or WP-CLI.
What could be causing a database connection error in WordPress?
A) The most common causes are: incorrect database credentials in wp-config.php, a wrong DB_HOST value, a crashed or stopped MySQL service, the server hitting its maximum allowed database connections under traffic load, corrupted database tables (which only show this error in wp-admin), and a plugin or theme that keeps connections open or sends malformed queries. When credentials are changed on the server side but not in wp-config.php, hosting migrations often cause the error.
How can I fix a WordPress database error without having access to wp-admin?
A) Most fixes don’t need wp-admin. You can use SFTP (FileZilla) or SSH to change the credentials in wp-config.php. To run the database repair tool, add define(‘WP_ALLOW_REPAIR’, true); to wp-config.php and go to /wp-admin/maint/repair.php. You don’t need to log in to this page. WP-CLI lets you fully repair your database over SSH with the commands wp db check and wp db repair. You can turn off a lot of plugins at once by renaming the /wp-content/plugins/ folder using SFTP.
Why does the database error only show up on the front end and not in wp-admin?
A) If you see the connection error on the frontend but wp-admin loads (even if only partially) and says “One or more database tables are unavailable,” The MySQL connection is fine, but one or more database tables may be broken, so you may need to fix the database. The connection error and the tables-unavailable error are two different problems. The first means that WordPress can’t connect to the database at all, and the second means that it can connect but some of the data inside is broken. Fix 4 talks about how to fix that problem.
Zain Imran
Zain is an electronics engineer and an MBA who loves to delve deep into technologies to communicate the value they create for businesses. Interested in system architectures, optimizations, and technical documentation, he strives to offer unique insights to readers. Zain is a sports fan and loves indulging in app development as a hobby.
