Your whole WordPress site just became one line: Error establishing a database connection.
That message means WordPress never got a MySQL handle. Wrong credentials in wp-config.php, a stopped database, a missing database name or a full connection pool are the usual causes, and each leaves a different clue.
We reproduced the common MySQL error codes on a lab box in November 2026. Below is how to read them and fix each one.
What does Error establishing a database connection mean?
WordPress prints that heading when wpdb::db_connect() fails. mysqli_real_connect errors out, the handle is cleared, and WordPress stops before themes or plugins run.
So this is not a theme bug and almost never a plugin bug. The app never got far enough to load them.
- Credentials or host wrong.
DB_NAME,DB_USER,DB_PASSWORDorDB_HOSTinwp-config.phpdo not match what MySQL expects. - Database server unreachable. MySQL is stopped, firewalled, or listening on another host or port.
- Server answered, then said no. Access denied, unknown database, host not allowed, or too many connections.
If MySQL accepts the login but cannot select the database, WordPress uses a different screen: Cannot select database. Same family, clearer cause.
Seeing this on a site you do not own?
You cannot edit their wp-config.php. A quick check still helps before you assume the site is gone.
- Wait a few minutes, then reload once. Hosts restart MySQL after brief overload, and a deploy can knock the database offline for a short window.
- Try the homepage and
/wp-admin/. Both fail the same way when the database is down. If only one URL fails, you are probably looking at a different error. - Skip clearing your browser cache. This page is generated on the server before any HTML cache helps.
Site owners: keep reading. The fix is almost always on the server.
We forced the same MySQL failures WordPress hits
Our setup, in November 2026: a Linux test box, Python with the pymysql client, and a tiny MySQL-protocol fake server that returned real error packets. No production WordPress site was touched.
WordPress wraps most of these into one screen. The numbers below are what the database client sees, and what your host logs will show.
| What we did | MySQL errno | Client message | How fast |
|---|---|---|---|
| Nothing listening on port 3306 | 2003 | Can’t connect … Connection refused | ~5 ms |
| Server returned Access denied | 1045 | Access denied for user ‘wpuser’@’…’ (using password: YES) | ~2 ms |
| Server returned Unknown database | 1049 | Unknown database ‘wrongdb’ | ~1 ms |
| Server returned Too many connections | 1040 | Too many connections | Under 1 ms |
| Server returned Host is not allowed | 1130 | Host ‘…’ is not allowed to connect | Under 1 ms |
| Accepted the TCP connection, then reset it | 2013 | Lost connection … Connection reset by peer | Under 1 ms |
| Accepted, then never sent a handshake (5 s timeout) | 2013 | Lost connection … (timed out) | ~5 s |
A refused connection is instant. Error 2003 came back in a few milliseconds. If your browser spun for half a minute first, look at timeouts and overload, not a simple wrong password.
Wrong password and missing database are different. 1045 means the user or password failed. 1049 means login got far enough to reject the database name. WordPress may still show the same public heading for both.
We did not boot a full WordPress stack here. The client errors match what mysqli reports. The public HTML heading comes from current WordPress core, which we read in source.
What causes this error on WordPress?
Work these in order. Stop when the site loads again.
1. Wrong credentials in wp-config.php
Most common after a migrate, a password rotate or a host panel rebuild. Open wp-config.php in the site root and match these four lines to your host’s database panel:
define( 'DB_NAME', 'your_database_name' );
define( 'DB_USER', 'your_database_user' );
define( 'DB_PASSWORD', 'your_database_password' );
define( 'DB_HOST', 'localhost' );Copy from the panel. Do not retype from memory. A single extra space in the password is enough.
Also watch DB_HOST. Hosts disagree on localhost, 127.0.0.1, a remote hostname or a socket path. localhost often uses a Unix socket; 127.0.0.1 forces TCP.
Real-world tip: after a migrate, confirm the new host created the database user and granted it rights on that database. Restoring files alone does not recreate MySQL users.
2. The database server is down or unreachable
In our lab, a closed port 3306 produced errno 2003 with Connection refused in about 5 ms. On a VPS you control:
sudo systemctl status mysql mariadb
sudo ss -lptn | grep -E '3306|mysql'On shared hosting, check the panel for a MySQL service notice and ask support if it is unclear. Outages and account suspensions both look like connection failures to WordPress.
3. Unknown database or no permission to use it
Errno 1049 means MySQL has no database with that name. Create it in the panel or fix DB_NAME, then grant the user full rights. Errno 1045 with a password you trust often means the user has no grant on that database.
WordPress has a separate bail message when login worked but select failed: Cannot select database. That means you already cleared the network and password hurdles.
4. Too many connections
Errno 1040 means MySQL hit max_connections. In our lab the refusal was under a millisecond. Pages may load, then fail again under traffic.
Restart MySQL or ask the host to clear stuck sessions. Then cut idle PHP workers and lean on full-page cache so WordPress opens fewer DB sessions. WP Rocket helps there; our speed up WordPress guide covers the rest of the stack.
5. Host not allowed / remote database rules
Errno 1130 means MySQL rejected the client host, often after a remote DB_HOST change or an app-server move while the user is still granted only for localhost. Update the grant to the new IP (or put the app back), and do not open MySQL to the whole internet casually.
6. Corrupted tables, bad prefixes, and what this error is not
Corrupt tables rarely cause the connect screen; MySQL accepts the login, then queries fail. Repair from phpMyAdmin or REPAIR TABLE once you can connect. A wrong $table_prefix usually means missing tables or login loops, not this heading. Plugins load after the DB connect, so they are not the first place to look.
How to fix it, step by step
Five minutes with the right checks usually names the culprit. Stop at the first step that restores the site.
Trace the database connection failure
Each step rules out a different cause.
-
Step 1 of 5
Confirm the exact message
Read the page heading. “Error establishing a database connection” is a connect failure. “Cannot select database” means login worked but DB_NAME or grants failed. A 502 or 503 is a different layer.
-
Step 2 of 5
Diff wp-config.php against the host panel
Match DB_NAME, DB_USER, DB_PASSWORD and DB_HOST character for character. Try localhost vs 127.0.0.1 if the host documents both.
-
Step 3 of 5
Test the database from the panel or CLI
phpMyAdmin, Adminer or mysql CLI with the same credentials. Access denied points at the user. Unknown database points at DB_NAME. Connection refused points at the service.
-
Step 4 of 5
Check MySQL is up and not full
Service status for 2003. Processlist or host metrics for 1040. Ask support to confirm max_connections on shared hosting.
-
Step 5 of 5
Repair only after you can connect
Once login works, repair crashed tables and verify $table_prefix. Then purge full-page and CDN cache so you are not staring at a cached error page.
# On a VPS you control (adjust user/host):
mysql -h 127.0.0.1 -u wpuser -p -e 'SELECT 1;'
mysql -h 127.0.0.1 -u wpuser -p -e 'SHOW DATABASES;'
sudo systemctl status mysql mariadbDatabase connection vs 502, 503, 504 and a critical error
People lump every white-ish failure together. The layer that broke is not the same.
| What you see | Which layer failed | Check first |
|---|---|---|
| Error establishing a database connection | MySQL / wp-config credentials | DB_* constants, MySQL service, grants |
| 502 Bad Gateway | Proxy could not get a valid reply from PHP/app | Is PHP-FPM running? |
| 503 Service Unavailable | Server refused the work (busy, limit, maintenance) | Maintenance file, rate limits, workers |
| 504 Gateway Timeout | Upstream took too long | Slow queries, external APIs |
| There has been a critical error… | PHP fatal after bootstrap | debug.log, recent plugin/theme change |
Our 502 Bad Gateway, 503 Service Unavailable and 504 Gateway Timeout guides cover the gateway family. A critical error means PHP already started and then crashed. Different fix path.
When the database error keeps coming back
A one-off after a password change is normal. Daily flaps at busy hours usually mean the database plan is too small, or something is leaking connections.
Cache first so WordPress opens MySQL less often. If the plan is the bottleneck, compare options in our managed versus shared hosting guide, and skim how web hosting works for where MySQL sits.
A larger Hostinger plan is often enough headroom for a small site. Prefer hands-off database care? Pressable handles that. Stage risky changes first with a tool from our WordPress sandbox list.
Disclosure: Hostinger, Pressable and WP Rocket links here are affiliate links. If you buy through them we may earn a commission. Your price stays the same.
Frequently Asked Questions
Is Error establishing a database connection the same as a white screen of death?
No. This error still prints a clear WordPress heading. A white screen of death is usually a PHP fatal with display_errors off. Both take the site down, but the logs and the fixes are not the same.
Can a plugin cause Error establishing a database connection?
Almost never on a normal boot. WordPress connects to MySQL before it loads plugins. A plugin can exhaust connections later and trigger reconnect failures, but wrong credentials and a down database are far more common.
Why does only wp-admin show the database error?
Usually it does not. Both front and admin need the same connection. If only admin fails, you may be hitting a different error, a redirected URL or a cached homepage still serving old HTML.
Should I delete and recreate the database to fix this?
Only if the database is truly missing and you have a fresh backup to import. Recreating an empty database with the old name fixes error 1049, but without a restore your content is gone.
Does localhost always work as DB_HOST?
No. Some hosts require 127.0.0.1, a remote hostname or a socket path instead. WordPress accepts host:port and host:/socket forms in DB_HOST. Use the exact value your host documents for WordPress installs.
Will this error hurt my Google rankings?
A short outage is usually fine. Hours or days of server errors can slow crawling and eventually drop URLs. Fix the database first, then check Search Console crawl stats if the outage lasted more than a day.
What is db-error.php in wp-content?
An optional drop-in. If that file exists, WordPress loads it instead of the default connection-error HTML and currently answers with HTTP 500. Useful for a branded maintenance page while you fix MySQL.
I fixed wp-config.php but still see the error. What next?
Confirm you edited the file on the server that actually serves the site, purge full-page cache and CDN cache, and retest credentials in phpMyAdmin. Then ask the host whether MySQL was restarted or the account limited.
The bottom line
An Error establishing a database connection means WordPress never reached MySQL. Match wp-config.php to the host panel, confirm the database service is up, then read the MySQL errno when you can: 1045 for credentials, 1049 for the database name, 2003 for a down host, 1040 for a full pool.
Gateway codes and critical errors are different layers. Fix the database first. If the site outgrew the plan, move up in hosting rather than patching the same outage every Monday.
