Codecondo

How to Fix Error Establishing a Database Connection in WordPress

Alex Ivanovs
error establishing a database connection

Table of Contents

  1. What Does “Error Establishing a Database Connection” Mean?
  2. Common Causes of the WordPress Database Connection Error
  3. How to Fix Error Establishing a Database Connection
    1. Check Whether the Problem Is Temporary
    2. Verify Your Database Credentials
    3. Check the Database Host
    4. Confirm the Database User Has Access
    5. Check Whether the Database Server Is Running
    6. Check Database Quotas and Hosting Resources
    7. Check for Database Corruption
    8. Temporarily Disable Plugins and Themes
    9. Review WordPress and Server Logs
    10. Check DNS, SSL and Server Configuration
    11. Restore a Known-Good Backup
  4. What Not to Do When Fixing a Database Connection Error
  5. WordPress Database Connection Troubleshooting Checklist
  6. Frequently Asked Questions
  7. Conclusion

What Does “Error Establishing a Database Connection” Mean?

The “Error Establishing a Database Connection” message appears when WordPress cannot connect to the database that stores your website’s content and configuration.

WordPress relies on a MySQL or MariaDB database for information such as posts, pages, users, settings, comments and plugin data. When WordPress cannot establish that database connection, it cannot retrieve the information required to generate the website. As a result, visitors may see an error page instead of your content, and the WordPress login area may also become unavailable.

The problem is not necessarily caused by incorrect login credentials.

A WordPress database connection error can also result from an unavailable database server, incorrect database host, missing permissions, exhausted hosting resources, database corruption, DNS or networking problems, or changes made during a migration or hosting configuration update.

WordPress’s official troubleshooting documentation identifies incorrect wp-config.php information and hosting/database availability as important causes.

Common Causes of the WordPress Database Connection Error

Before changing files or database settings, identify which part of the connection is failing.

Possible Cause What It Means
Incorrect database name WordPress is pointing to a database that does not exist or is not the intended database
Incorrect database username The configured user is wrong or no longer exists
Incorrect database password The password in wp-config.php does not match the database user’s password
Incorrect DB_HOST WordPress is trying to connect to the wrong database server or port
Missing database permissions The database user does not have access to the selected database
Database server outage MySQL or MariaDB is unavailable
Hosting resource limits The account has reached a connection, memory, storage or database quota
Database corruption One or more database tables may be damaged
Plugin or theme problem A component may be causing excessive queries or another server-side failure
DNS or networking issue WordPress cannot reach the database or related infrastructure
Migration configuration error Database details changed during a host or server migration
Security or server configuration Firewall, access-control or server rules may prevent the connection

This is why simply changing the database password is not always the correct solution.

How to Fix Error Establishing a Database Connection

Work through the following steps in order. If your website contains important business or customer data, create or confirm a recent backup before making database or file changes.

1. Check Whether the Problem Is Temporary

First, determine whether the error is persistent.

If the website suddenly stopped working after previously operating normally, check:

If the site returns to normal after a short period, the database server or hosting environment may have experienced a temporary availability or resource problem.

If the error continues, move to the configuration checks below.

2. Verify Your Database Credentials

One of the first things to check is the database information in your wp-config.php file.

WordPress uses four primary database settings:

define( ‘DB_NAME’, ‘database_name’ );

define( ‘DB_USER’, ‘database_user’ );

define( ‘DB_PASSWORD’, ‘database_password’ );

define( ‘DB_HOST’, ‘database_host’ );

These values need to match the database configuration supplied by your hosting provider. WordPress’s official documentation confirms that wp-config.php contains the database connection information, including the database name, username, password and host.

You can usually access wp-config.php through:

Before editing the file, download a backup copy.

Important: Do Not Confuse WordPress Login Credentials With Database Credentials

Your WordPress administrator username and password are different from the credentials WordPress uses to connect to MySQL or MariaDB.

Changing your WordPress admin password will not fix a database connection problem.

Similarly, database credentials are configured in wp-config.php; they are not something you should create or modify in the WordPress wp_options table.

3. Check the Database Host

DB_HOST tells WordPress where the database server is located.

A common configuration is:

define( ‘DB_HOST’, ‘localhost’ );

However, localhost is not universal.

Depending on your hosting environment, the database host might be:

For example:

define( ‘DB_HOST’, ‘localhost:3307’ );

Do not randomly replace localhost with an IP address. Confirm the correct database host and port with your hosting provider.

WordPress documentation specifically notes that a database host can include a port number or Unix socket path when required by the hosting environment.

4. Confirm the Database User Has Access

Having the correct username and password is not enough if the database user does not have permission to access the database.

In your hosting control panel, look for an area such as:

Confirm that:

  1. The database exists.
  2. The database user exists.
  3. The user is assigned to the correct database.
  4. The user has the required permissions.
  5. The database name matches DB_NAME.
  6. The username matches DB_USER.

If you recently migrated your WordPress site, pay particular attention to this step because database names and usernames can change between hosting environments.

5. Check Whether the Database Server Is Running

If the credentials are correct but WordPress still cannot connect, the database service itself may be unavailable.

This is especially relevant for:

If you have server access, check whether MySQL or MariaDB is running and review its service logs.

If you use managed or shared hosting, contact your hosting provider and ask them to confirm:

WordPress’s official documentation also recommends contacting the host when the configuration appears correct but the hosting environment may be responsible.

6. Check Database Quotas and Hosting Resources

A website can experience a database connection failure even when its credentials are correct.

Check whether your hosting account has reached:

Shared hosting environments can be particularly sensitive to resource limits because multiple websites may share server resources.

If the error appears during traffic spikes, automated tasks or heavy database activity, ask your host whether the account is reaching a resource or connection limit.

7. Check for Database Corruption

If the database is accessible but one or more tables are damaged, WordPress may fail to operate correctly.

Always create a database backup before attempting repairs.

WordPress provides a built-in database repair mechanism that can be enabled with:

define( ‘WP_ALLOW_REPAIR’, true );

The repair tool is available at:

/wp-admin/maint/repair.php

WordPress notes that this functionality does not require a user to be logged in, because it is designed for situations where users cannot access the site. For that reason, the setting should be removed from wp-config.php immediately after troubleshooting is complete.

For more advanced administrators, WP-CLI can also interact with the WordPress database. For example, wp db connect opens a MySQL console using the credentials configured in wp-config.php.

If you are not comfortable working directly with MySQL or MariaDB, ask your hosting provider or a qualified WordPress professional to perform the repair.

8. Temporarily Disable Plugins and Themes

Plugins and themes do not normally cause a basic database authentication failure, but a faulty or resource-intensive extension can contribute to database-related failures, timeouts or server instability.

If you can access WordPress, temporarily deactivate recently changed plugins.

If you cannot access the dashboard, you can use SFTP or your hosting File Manager to rename the plugins directory:

wp-content/plugins

For example:

wp-content/plugins-disabled

This can temporarily deactivate the installed plugins.

WordPress also documents manual plugin deactivation when the administration area is unavailable.

If the problem disappears, restore the original folder name and reactivate plugins individually to identify the problematic component.

Do not immediately delete plugins or database tables. The goal at this stage is diagnosis, not permanent removal.

9. Review WordPress and Server Logs

Logs can reveal more information than the generic database connection message.

Depending on your hosting environment, check:

For temporary troubleshooting on a development or staging environment, WordPress supports WP_DEBUG and WP_DEBUG_LOG.

For example:

define( ‘WP_DEBUG’, true );

define( ‘WP_DEBUG_LOG’, true );

 

WordPress cautions against using debug display settings on live production websites because errors can expose technical information to visitors. Debugging should therefore be handled carefully and disabled or appropriately configured after troubleshooting.

10. Check DNS, SSL and Server Configuration

If your WordPress site uses a separate database server or a more complex cloud architecture, networking can also become part of the problem.

Check whether:

For websites using managed WordPress hosting, these checks are often handled by the hosting provider.

11. Restore a Known-Good Backup

If the database has been damaged and repair attempts do not resolve the issue, restoring a known-good backup may be the safest option.

Before restoring:

  1. Preserve the current database and files.
  2. Confirm when the website was last working correctly.
  3. Identify the most recent clean backup.
  4. Verify that the backup contains both the database and required WordPress files.
  5. Check whether newer orders, posts, comments or customer records would be lost.
  6. Test the restored site in a staging environment when possible.

Database restoration should be treated as a recovery procedure rather than the first troubleshooting step.

What Not to Do When Fixing a Database Connection Error

Some troubleshooting techniques commonly recommended in older WordPress articles are no longer appropriate.

Do Not Create a Public connectiontest.php File

Creating a publicly accessible PHP file to test database credentials can expose unnecessary information and leave an additional file on your server.

Use your hosting tools, WP-CLI, server logs or a controlled administrative environment instead.

Do Not Store Database Credentials in wp_options

Database connection credentials belong in WordPress configuration, normally wp-config.php. The wp_options table contains WordPress settings and plugin/theme options; it is not where you should create database connection credentials.

Do Not Randomly Change DB_HOST

Changing localhost to an arbitrary IP address or hostname can create additional problems. Obtain the correct value from your hosting environment.

Do Not Delete Database Tables Without a Backup

Database tables can contain posts, users, orders, settings and other critical information.

Never delete tables simply because they appear unfamiliar.

Do Not Enable Debugging Permanently on a Production Site

Debugging can expose errors and technical information. Use it temporarily and configure it appropriately for the environment.

WordPress Database Connection Troubleshooting Checklist

Use this checklist when your WordPress website displays the error establishing a database connection message.

Check What to Verify
Database exists The configured database is present on the server
DB_NAME Matches the actual database name
DB_USER Matches the assigned database user
DB_PASSWORD Matches the database user’s current password
DB_HOST Matches the host-provided database endpoint
Database permissions User can access the database
Database server MySQL/MariaDB service is available
Hosting resources No storage, memory or connection quota has been reached
Database health Tables are accessible and not corrupted
Plugins Recent or problematic plugins are ruled out
Themes Recent theme changes are ruled out
Logs PHP, WordPress and database errors have been reviewed
DNS/network Database hostname and network access work correctly
Backups A current backup exists before making major changes

Frequently Asked Questions

What is the fastest way to fix “Error Establishing a Database Connection” in WordPress?

Start by checking DB_NAME, DB_USER, DB_PASSWORD and DB_HOST in wp-config.php. If those values are correct, check database availability, user permissions, hosting resource limits and server logs. WordPress identifies incorrect configuration and hosting/database availability among the common causes.

Why does WordPress say “Error Establishing a Database Connection”?

The message means WordPress cannot establish the required connection to its MySQL or MariaDB database. The cause can be incorrect credentials, an incorrect database host, missing permissions, an unavailable database server, resource limits, networking problems or database corruption.

Can a wrong WordPress password cause a database connection error?

No. Your WordPress administrator password and your database password are separate credentials. A database connection error is related to the credentials and connection information WordPress uses to access MySQL or MariaDB.

Where are WordPress database credentials stored?

The standard database connection settings are stored in wp-config.php, including DB_NAME, DB_USER, DB_PASSWORD and DB_HOST.

Can a plugin cause a WordPress database error?

A plugin can contribute to database-related problems through excessive queries, compatibility problems, resource consumption or other application errors. Temporarily disabling plugins can help determine whether a plugin is involved.

Should I repair the WordPress database?

Database repair can help when tables are corrupted, but you should create a backup first. WordPress provides a built-in repair feature through WP_ALLOW_REPAIR; because the repair page does not require login, remove the setting after completing the repair.

What database does WordPress use?

WordPress officially supports MySQL and MariaDB. The current WordPress requirements recommend MySQL 8.0+ or MariaDB 10.11+, along with PHP 8.3 or greater.

Can outdated hosting cause database connection problems?

Yes. Legacy PHP or database versions can create compatibility, security and reliability concerns. WordPress currently recommends PHP 8.3+ and MySQL 8.0+ or MariaDB 10.11+.

Conclusion

The error establishing a database connection message does not automatically mean that your WordPress database credentials are wrong. Troubleshooting should take a broader approach that considers configuration, database permissions, hosting resources, MySQL or MariaDB availability, database health, plugins, server logs and network configuration.

Start with the safest checks: confirm the database name, username, password and host in wp-config.php. Then verify that the database server is available and that the configured user has access to the correct database.

If the configuration is correct, investigate hosting resources, database corruption, plugins, logs and server-side networking. Always back up the database before making significant changes, and avoid insecure troubleshooting methods such as exposing database credentials through a publicly accessible test script.

Keeping WordPress, PHP and your database platform on supported versions is also an important part of long-term reliability and security. Current WordPress requirements recommend PHP 8.3 or greater and MySQL 8.0 or MariaDB 10.11 or greater.

With a systematic troubleshooting process, most WordPress database connection errors can be narrowed down to a specific configuration, hosting or database problem instead of requiring a complete WordPress reinstall.

Exit mobile version