You load the site and get a white page with one line on it: "Error establishing a database connection." No theme, no admin panel, no hint. I’ve seen this screen more often right after migrations and host moves than at any other time, and the fix is usually boring. The trick is to check things in the right order and not start "repairing" a database that was never broken.
Here is the short version. There are four usual causes:
- Wrong credentials in wp-config.php
- The database server is down or over its quota
- Corrupted tables
- A host or migration change that left old settings behind
Work from the fastest check to the slowest. Most of the time you’ll be done at step one.
What the error establishing a database connection message actually means
WordPress builds every page from its database. When PHP can’t log in to MySQL, WordPress gives up and shows this message instead. The WordPress common errors guide says it means there is a problem connecting to your database, that there are several possible reasons, and that it is usually caused by an error in wp-config.php.
That last part matters. The message is about the connection, not about your content. Your posts are almost always still sitting in the database, untouched. So before you do anything drastic, here is what to leave alone:
- Don’t reinstall WordPress.
- Don’t restore last week’s full backup over everything.
- Don’t start turning off plugins. They can’t even load right now.
Check wp-config.php credentials first
The wp-config.php file sits in the root of your WordPress files and holds the database connection details. Open it through FTP or your host’s file manager, and download a copy before you change a thing. The wp-config.php documentation is clear on this: back up first and know how to restore it.
You’re checking four values:
define( 'DB_NAME', 'example_db' );
define( 'DB_USER', 'example_user' );
define( 'DB_PASSWORD', 'example-password' );
define( 'DB_HOST', 'localhost' );
Compare each one against what your host’s control panel shows. Then look for the small stuff that breaks big things: a stray space inside the quotes, a single quote that got deleted, or anything sitting after the closing PHP tag. Nothing should come after it.
If the four values look right, reset the MySQL user’s password by hand in your host’s panel and paste the new one into the file. Copying passwords between systems is where typos love to hide.
While you’re in there, glance at $table_prefix. It’s the value placed in front of your table names. A mismatch tends to show up as a fresh install screen rather than this error, but it’s worth a look after any move.
Want more detail? Database errors are only printed if WP_DEBUG is true. On a staging copy, add this before the line that says /* That's all, stop editing! Happy blogging. */:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
That writes errors to wp-content/debug.log and keeps them off the screen. Two catches. The log and display settings only work when WP_DEBUG is true, and true and false must not be in quotes, because 'false' as a string is read as true. WordPress doesn’t recommend debug tools on live sites. If you turn them on briefly anyway, know that the default log is publicly reachable. Move it above the web root, or set its permissions to 600 and block it in .htaccess. Then turn debugging off.
Confirm the database server is running
If the credentials are right, look at the server. WordPress names two hosting problems that cause this error: the database hit its quota and got shut down, or the server itself is down. Either way, your host has to confirm it. When a live site is failing right now, emergency WordPress support is a faster path than a rebuild.
You can narrow it down before you open a ticket:
- Try phpMyAdmin. Log in with the same username and password from wp-config.php. If phpMyAdmin can’t connect either, the problem isn’t WordPress.
- Check your other sites. If every site on that host is down, it’s the server.
- Check database size. If your panel shows the database near its limit, say so in the ticket.
If you have SSH access, mysqlcheck doubles as a connection test, since the MySQL manual notes it only runs while the server is running. The default host is localhost and the default port is 3306. Don’t type your password on the command line. Use -p alone and let the tool prompt you:
mysqlcheck -u example_user -p example_db
If that connects and checks your tables, the server is up and you’ve ruled out a whole category.
Repair corrupted tables and fix the site URL
Corruption is less common than a typo, but it happens. If you see error 145 anywhere, that means a table is damaged. Back up the database before you touch it. If phpMyAdmin makes you nervous, ask your host to run CHECK and REPAIR for you. That’s a fair request.
The WordPress way. Add this to wp-config.php:
define( 'WP_ALLOW_REPAIR', true );
Then visit yoursite.com/wp-admin/maint/repair.php. While this setting is on, anyone can reach that page with no login. Run the repair and remove the line right after.
The MySQL way. Checking is what mysqlcheck does by default. The repair option (-r) can fix almost anything except unique keys that aren’t unique. A few things to know first:
- InnoDB tables can be checked but not repaired this way. For those, the manual points to manual repair strategies, which is a job for your host or a DBA.
- A repair can lose data in some cases, so back up the table first.
- Each table is locked while it’s processed, and big databases take a while. Do it off-hours.
About the site URL. If you moved domains, the old address is still stored in the options table. That usually won’t cause this exact error. It causes the next problem: redirects to the old domain or a login page that loops. Update the two address values in the options table through phpMyAdmin, or check the current WordPress docs for the method your setup supports.
If wp-config.php checks out and the host says everything is fine, WordPress suggests the site may have been hacked. Run it through a reputable malware scanner before you dig deeper.
When the error shows up after a migration or host move
Here is a made-up example. A small catering company moves its WordPress site to a new host late on a Friday. Files get copied, the database gets imported, DNS gets switched. The site loads the error screen.
The owner’s first instinct is to restore a backup. Instead, someone opens wp-config.php. It still has the old host’s database user and host value. The new host had also added an account prefix to the database name, which the old file didn’t have. They update the four values and the site comes back in about twenty minutes. Then the menu links point to the old domain, so they fix the address values too. Nothing was corrupted. Nothing needed a restore.
That’s the usual shape of it. After a move, check these:
- DNS. Are you looking at the old server, where the database may already be deleted?
- User privileges. Was the database user actually assigned to the new database?
- DB_HOST. Some hosts don’t use localhost. Get the value from the new host’s panel.
- The import. Did it finish, or did it time out halfway through?
Don’t run repairs just because a move happened. For a longer walkthrough, see this post-migration recovery example.
How to stop it from coming back
The repeat is usually a process problem, not a technical one. A few habits help:
- Keep a move checklist with the four database values and where each one comes from.
- Test restoring a backup before you need it.
- Watch database size against your host’s quota.
- Do debugging on staging, not on the live site.
- Remove
WP_ALLOW_REPAIRonce you’re done. - Decide who owns the site after launch. Our piece on who maintains integrations after launch covers the same question for connected systems.
If you’d rather hand the move and the checklist to someone else, Parameter does WordPress host transitions and ongoing site ops. You’ll find answers to common questions on our FAQ page. Either way, start with wp-config.php. It’s the right first step more often than anything else.
Want WordPress to feel handled?
Self-serve onboarding takes minutes. Parameter takes care of the rest, hosting, ops, and improvements when you need them.