How to Fix "Error Establishing a Database Connection" in WordPress Print

  • wordpress, database, database-connection, wp-config, mysql, troubleshooting, error-establishing-database-connection
  • 0

What the error actually means

A WordPress site that suddenly displays "Error establishing a database connection" is not broken beyond repair. The message means WordPress could not log in to its MySQL or MariaDB database. In most cases the cause is a wrong credential, a removed database user, or a server-side problem that can be identified in a few minutes.

This guide works through the causes in a deliberate order, from the least disruptive checks to the most disruptive. Follow it from the top rather than trying fixes at random, and change only one thing at a time.

Important: Do not reinstall WordPress or import a backup before you know which layer failed. Reinstalling files does not fix a database problem, and restoring over a working database can destroy data you could otherwise have recovered.

WordPress stores posts, pages, users, settings, and most plugin data in a database. During startup, the wpdb class reads four values from wp-config.php and opens a connection to the database server:

  • DB_NAME — the database name.
  • DB_USER — the database username.
  • DB_PASSWORD — the database user's password.
  • DB_HOST — the database server, usually localhost on cPanel hosting.

If that connection cannot be opened, WordPress stops before themes and plugins load. This is why the whole site goes down, and why disabling plugins usually changes nothing. The message is deliberately generic, so the first task is to make WordPress reveal the underlying database error.

Before you begin

  • Back up the database first. Use the database backup procedure in "How to Back Up and Restore a WordPress Database", or the partial database download described in How to Take a Full cPanel Backup (and Restore It).
  • Know your access level. Shared and reseller hosting customers have cPanel access but no root access. VPS customers may have root. Coolify and Docker deployments need container-specific checks.
  • Never post database passwords in a public forum, chat, or screenshot.
  • Expect 15 to 40 minutes. Most cases are resolved at Step 3 or Step 5.

Plan limitation: On shared hosting you cannot restart the database service, read the server's database log, or change server-wide connection limits. Steps that require those actions are marked as VPS-only.

Step 1: Locate wp-config.php

The file is normally in the WordPress installation directory, such as public_html or a subdirectory for a site installed in a folder. WordPress also checks one level above the installation directory if the file is not found in the site root, so some managed setups keep it outside the web root.

  1. In cPanel, open Files then File Manager.
  2. Open the directory that contains wp-load.php and wp-config.php.
  3. Download a copy of wp-config.php to your computer before editing it.

Security: Do not leave a copy named wp-config.php.bak inside public_html. Some web servers will serve a backup file as plain text, exposing your database password. Keep the copy on your computer or outside the web root.

Step 2: Make WordPress show the real database error

WordPress only prints database errors when WP_DEBUG is enabled. Add these three lines to wp-config.php, above the line that reads /* That's all, stop editing! Happy blogging. */:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

This writes errors to wp-content/debug.log instead of showing them to visitors. Reload the broken page, then open wp-content/debug.log in File Manager or download it. Look for the line that mentions the database, the username, or the database host.

If you cannot edit files on your plan, check cPanel then Metrics then Errors, or ask SysopHost support for the PHP error log entry for the affected timestamp.

If the page changes from the database error to a blank page or a PHP parse error, your edit introduced a syntax error. Restore the copy of wp-config.php immediately and reapply the change carefully.

Security: Debug mode is temporary. After diagnosis, set WP_DEBUG to false, delete wp-content/debug.log, and confirm the site loads normally.

Reading the error message

Exact wording varies between MySQL and MariaDB versions, but the key phrases are consistent:

Message contains Likely cause Go to
Access denied for user Wrong username or password, or the user has no access to this database Step 3 and Step 5
Unknown database Wrong DB_NAME, or the database was deleted Step 4
Can't connect to local MySQL server through socket Database service down, or wrong socket path Step 7
Can't connect to MySQL server on Wrong host, blocked port, or database in another container Step 7 or Step 9
Too many connections Traffic spike, runaway plugin, or low connection limit Step 7
marked as crashed or error 145 Corrupted table Step 8
MySQL server has gone away Timeout, restart, or oversized query Step 7

Step 3: Verify the four database constants

Open wp-config.php and compare the four values with what your hosting account actually provides:

define( 'DB_NAME', 'example_wp' );
define( 'DB_USER', 'example_wpuser' );
define( 'DB_PASSWORD', 'your-password' );
define( 'DB_HOST', 'localhost' );

The values must match exactly, including letter case and any prefix. cPanel often prefixes database and user names with the account username, so the real names may look like example_wp and example_wpuser rather than wp and wpuser.

Common mistakes to check:

  • The database username was confused with the cPanel login name or an email address.
  • The account prefix was omitted from DB_NAME or DB_USER.
  • The password was changed in cPanel but not updated in wp-config.php.
  • DB_HOST was changed to an IP address or hostname that is not the database server.
  • The file contains curly quotes instead of straight single quotes, usually after editing in a word processor.
  • A semicolon is missing at the end of a line.

In cPanel, open Databases then MySQL Databases. In cPanel version 120 and later this interface is named Manage My Databases; the fields are the same. The Current Databases table shows the full database name and its privileged users.

DB_HOST is usually localhost on cPanel plans. Some hosts run a separate database server and display its address in the Remote MySQL Host section. Use the exact value SysopHost provides, and do not substitute an address you found elsewhere.

For a detailed field-by-field procedure, see "How to Find, Verify, and Reset WordPress Database Credentials in cPanel".

Step 4: Confirm the database still exists

In cPanel, check the Current Databases table. In phpMyAdmin, the database should appear in the left-hand list. If the database is missing, do not create an empty database with the same name and expect the site to return. The tables are gone. Restore the most recent backup, or ask support whether a provider-side backup is available for your plan.

Step 5: Confirm the user exists and has privileges

A database user can exist without being attached to the WordPress database. In that case the password may be correct and the connection will still be refused.

  1. In cPanel, open Databases then MySQL Databases.
  2. In Current Databases, check the Privileged Users column for the WordPress database.
  3. If the user is missing, use Add User To Database, select the user and the database, and click Add.
  4. Select ALL PRIVILEGES and click Make Changes.

Note: cPanel's documentation warns against creating databases or database users in phpMyAdmin, because phpMyAdmin does not update cPanel's database map and backups may then fail. Use the cPanel database interfaces for creation and privilege changes.

Warning: if the same database user is shared with another site or application, changing the password will break that application too. Check before you reset.

Step 6: Test the credentials directly

Testing outside WordPress separates a credential problem from a WordPress problem. On a VPS or any plan with SSH access:

mysql -h localhost -u example_wpuser -p example_wp -e "SELECT 1;"

Replace example_wpuser with the database user and example_wp with the database name. The -p option prompts for the password, which keeps it out of your shell history. A successful connection returns a single row containing 1.

  • Access denied: the username or password is wrong, or the user lacks access to this database.
  • Unknown database: the database name is wrong or the database does not exist.
  • Socket or connection error: the database service is unavailable or listening somewhere else. Continue to Step 7.

If WP-CLI is installed, run it as the account user from the WordPress directory:

cd /home/example/public_html
wp db query "SELECT 1;"

This uses the same values from wp-config.php, so a success proves the file's credentials work. Do not run WP-CLI as root: it can create root-owned files that break later updates.

If neither command is available on your plan, use phpMyAdmin to confirm the database and tables exist, and rely on the debug log for the specific error.

Step 7: Rule out server-side problems

Shared hosting and cPanel

  • Check whether other sites on the same account also fail. If they do, the problem is likely account-wide or server-wide.
  • Check disk usage and inode usage in cPanel. A full disk or exhausted inode quota can prevent database writes. See Inode Limit Exceeded in cPanel.
  • Check whether your plan enforces a database size limit.
  • If the database server is down, only the provider can restore it. Contact SysopHost support with the exact error and the time the site failed.

VPS administrators

Check the service. The unit is usually mariadb on MariaDB systems and mysql on MySQL systems:

systemctl status mariadb

If that unit does not exist, try:

systemctl status mysql

Then test whether the server responds and whether the disk has space:

mysqladmin ping
df -h
df -i

A healthy server reports mysqld is alive. Check both block usage and inode usage: a disk can have free space and still be unable to create files. Database error logs are commonly at /var/log/mysql/error.log or /var/log/mariadb/mariadb.log, depending on the distribution.

Do not disable the firewall to test the connection. If you suspect a port problem, confirm what is listening with ss -lntp | grep 3306 and, if a temporary rule change is genuinely required, scope it to one source address and revert it immediately afterwards.

Coolify and Docker

Inside a container, localhost refers to the WordPress container, not the database container. DB_HOST must be the database service name on the shared Docker network, and the port must be the internal container port. See the Coolify-specific guidance in "WordPress on Coolify or Docker: Fix Error Establishing a Database Connection".

Step 8: Check for a corrupted table

Only take this path if the log mentions a crashed or corrupted table, or MySQL error 145. Back up the database before running any repair, because repair operations can cause data loss. Then follow "How to Check and Repair a Corrupted WordPress Database".

Be aware that MySQL's REPAIR TABLE works only for MyISAM, ARCHIVE, and CSV tables. WordPress tables commonly use InnoDB, where repair is not supported. For InnoDB, a clean backup and restore is usually the correct fix.

Step 9: If the site was recently moved or migrated

A migration introduces a different set of causes: the old host or database name is still in wp-config.php, the dump was imported into a differently named database, the database user was never created on the new server, or DB_HOST still points at the old infrastructure. See "Database Connection Error After Migrating WordPress".

Step 10: Restore or escalate

If the database is damaged beyond repair and you have a verified backup, restore it. If you do not have a backup, ask support whether a provider-side backup exists for your plan before making further changes.

When contacting support, include:

  • The exact database error line from debug.log, with credentials masked.
  • When the failure started, including your time zone.
  • Any change made shortly before the failure: plugin update, PHP version change, migration, password reset, or DNS change.
  • The database name shown in cPanel.
  • What you have already tried and the result of each step.
  • Whether other sites on the same account are affected.

Do not send your database password. Support can verify access without it, and any password sent in plain text should be treated as exposed.

Verify the fix

  • The site home page and a few inner pages load without the error.
  • You can log in at /wp-admin.
  • wp-content/debug.log contains no new database errors after a fresh page load.
  • WP_DEBUG is set back to false and the log file has been deleted.
  • Content and settings are intact. If you restored a backup, confirm that recent posts, orders, or form entries are present.

Security considerations

  • Set wp-config.php permissions to 600 or 640. Never use 777.
  • Use a separate database user for each WordPress site, with privileges only on that site's database.
  • Do not leave debug mode enabled on a production site.
  • Reset any database password that has been shared in a ticket, chat, or screenshot.
  • Delete database dumps from the web root after use.

Related articles

If the issue persists after completing these steps, contact SysopHost support and include the exact error message, when the issue occurred, and the troubleshooting steps you have already completed. If other sites on the same account are also failing, say so in the ticket: that usually indicates a server-side problem rather than a WordPress configuration error.


Was this answer helpful?

« Back