--- title: "Error establishing a database connection: how to fix it" date: "2026-09-02" updated: "2026-09-02" excerpt: "The WordPress database error has four common causes. How to tell them apart in a couple of minutes, fix each one, and avoid the advice that makes it worse." tags: ["WordPress", "Debugging", "Hosting"] draft: false category: "guide" tldr: "This error means WordPress can't reach MySQL, nothing more. Check whether the database server is up, verify the four credentials in wp-config.php, test the connection independently, then rule out a corrupted database or a resource limit." howToSteps: - name: "Check whether the database server is up" text: "Try logging into phpMyAdmin or Adminer, or run systemctl status mysql on a server you control. Check disk space and memory with df -h and free -m before restarting a stopped service." - name: "Check the four credentials in wp-config.php" text: "Compare DB_NAME, DB_USER, DB_PASSWORD, and DB_HOST against what your hosting panel shows. DB_HOST is the value people get wrong most often." - name: "Test the credentials independently" text: "Run mysql -u DB_USER -p -h DB_HOST DB_NAME directly. If it connects, the credentials are fine and the fault is elsewhere." - name: "Rule out a corrupted database" text: "If the site loads but the admin shows a repair message, enable WP_ALLOW_REPAIR in wp-config.php, run the repair at /wp-admin/maint/repair.php (or wp db repair with WP-CLI), then remove the flag." - name: "Consider resource limits" text: "Intermittent failures under load usually point to a connection limit or a struggling server, not bad configuration, which fails consistently every time." faqs: - question: "What does 'Error establishing a database connection' actually mean?" answer: "It means WordPress could not talk to MySQL. The message is identical whether the cause is wrong credentials, a down database server, a corrupted database, or a host cutting you off for using too many resources." - question: "Will reinstalling WordPress fix a database connection error?" answer: "No. The error is about connecting to the database, not about WordPress's core files, so reinstalling changes nothing and risks your customizations." - question: "Should I restore an old backup first?" answer: "Not as a first move. Restoring a backup usually loses recent content to fix something that is often a one-line credential change." - question: "How do I tell a resource limit apart from a configuration problem?" answer: "Configuration problems are consistent: wrong credentials fail every time. If the error comes and goes, look at server load, slow queries, and your host's resource usage reports." --- "Error establishing a database connection" means WordPress could not talk to MySQL. That's all it means. The message is identical whether your credentials are wrong, the database server is down, the database is corrupted, or the host has cut you off for using too many resources. That is why generic fixes so often miss. Work through the causes in order. It takes about two minutes to find which one you have. ## Is the database server even up? If your host gives you phpMyAdmin or Adminer, try logging in. If that fails too, WordPress isn't your problem. The database server is down or unreachable, and this is a hosting issue rather than a site issue. On a server you control, check the service directly: ``` systemctl status mysql ``` A stopped service is usually either a crash after running out of memory, or a disk that has filled up. Check both before restarting, or you will be doing this again within the hour: ``` df -h free -m ``` A full disk is the single most common cause I see on small VPS installations, and it is often the logs that filled it. ## Then check the credentials WordPress reads four values from `wp-config.php`: ``` define( 'DB_NAME', '...' ); define( 'DB_USER', '...' ); define( 'DB_PASSWORD', '...' ); define( 'DB_HOST', 'localhost' ); ``` These break after a migration, after a host resets a password, or after someone edits the file and leaves a stray character. Compare each against what your hosting panel shows. `DB_HOST` is the one people get wrong. It is `localhost` on most shared hosting, but managed hosts frequently use a dedicated hostname, and some require a port or socket path. Copy it exactly rather than assuming. ## Test the credentials independently Rather than editing `wp-config.php` repeatedly and reloading the site, test the connection on its own: ``` mysql -u DB_USER -p -h DB_HOST DB_NAME ``` If that connects, your credentials are fine and the fault is elsewhere. If it rejects you, you have found the problem, and no amount of WordPress troubleshooting would have helped. ## Rule out a corrupted database If the site loads but the admin shows a different message (often mentioning that the database needs repairing), you likely have a crashed table. WordPress has a built-in repair mode. Add this to `wp-config.php`: ``` define( 'WP_ALLOW_REPAIR', true ); ``` Then visit `/wp-admin/maint/repair.php` and run the repair. **Remove that line as soon as you're done.** The repair page is deliberately accessible without logging in, so leaving it enabled leaves a maintenance tool exposed to anyone who finds the URL. With WP-CLI the same job is cleaner, and doesn't expose anything: ``` wp db repair ``` ## Consider resource limits On shared hosting, a burst of traffic or one expensive query can push you past a connection limit. The site then fails intermittently (fine on reload, broken a minute later), which is the signature symptom. Intermittent failures point at limits or a struggling server, not at configuration. Configuration problems are consistent: wrong credentials fail every single time. If yours comes and goes, look at load, slow queries, and whatever your host reports for resource usage. ## What not to do - **Don't reinstall WordPress.** The error is about connecting to the database. Replacing core files changes nothing and risks your customisations. - **Don't restore an old backup as a first move.** You will lose recent content to fix something that is often a one-line credential change. - **Don't paste `wp-config.php` into a support forum.** It contains your database password. If you already have, change that password. ## Keeping it from recurring If it was disk space, add monitoring and log rotation. If it was a crashed table, check whether the server is being shut down uncleanly. If it was resource limits, the honest answer is usually that the site has outgrown its plan. No amount of tuning fixes an underpowered box forever. For the routine work that catches most of this early, see [a WordPress maintenance checklist that prevents problems](/blog/wordpress-maintenance-checklist). If your site is currently offline and you need an urgent fix without risking data corruption, learn about my [WordPress emergency site recovery](/wordpress-site-recovery) and [WordPress technical support](/wordpress-support).