Fix Error Establishing a Database Connection on Localhost

Complete Troubleshooting Guide

Few WordPress errors are as frustrating as seeing Error Establishing a Database Connection when working on a local WordPress installation. Your website may have been working perfectly one minute, then suddenly refuse to load the dashboard or front end.

The good news is that this error is usually fixable.

When WordPress runs on localhost, the problem is often caused by incorrect database credentials, a stopped MySQL/MariaDB service, a damaged database, or incorrect settings in the `wp-config.php` file. Local development environments such as XAMPP, WAMP, MAMP, Local, and similar tools can also introduce their own configuration issues.

In this guide, we’ll show you how to fix error establishing a database connection on localhost, even if you’re relatively new to WordPress development.

The Core Basics

Before troubleshooting the problem, it helps to understand what WordPress is actually doing.

WordPress has two major components: the website files and the database.

Your WordPress files contain PHP code, themes, plugins, images, and configuration files. The database stores information such as posts, pages, users, settings, comments, and plugin data.

When somebody visits your WordPress website, WordPress uses PHP to communicate with the MySQL or MariaDB database. It requests the information required to construct the page and then displays it in the browser.

On localhost, everything is running on your own computer rather than a remote web server.

The term localhost generally refers to your own computer acting as the web server. Depending on your setup, you might access WordPress through an address such as:

* `http://localhost/wordpress`
* `http://localhost:8080/wordpress`
* A local domain configured by your development application

The database server is separate from the web server, even though both are running on the same machine.

That’s important.

If Apache or Nginx is running but MySQL/MariaDB isn’t, WordPress can’t retrieve its data. The result is the database connection error.

 Step-by-Step Guide to Fix the Database Connection Error

1. Check That Your Database Server Is Running

Start with the simplest possible explanation.

If you’re using XAMPP, WAMP, MAMP, or another local development environment, open its control panel and check whether MySQL or MariaDB is running.

For example, with XAMPP you should normally see Apache and MySQL running.

If MySQL is stopped, start it and then reload your WordPress website.

This alone can resolve the problem.

If MySQL refuses to start, don’t repeatedly restart it. There may be a port conflict or another database service already running on your computer.

2. Check Your `wp-config.php` Credentials

One of the most common causes is incorrect database information.

Open your WordPress installation folder and locate:

`wp-config.php`

Look for these settings:

“`php
define( ‘DB_NAME’, ‘database_name’ );
define( ‘DB_USER’, ‘database_user’ );
define( ‘DB_PASSWORD’, ‘database_password’ );
define( ‘DB_HOST’, ‘localhost’ );
“`

The values must match your local database configuration.

Check each one carefully.

**DB_NAME** must be the exact name of the WordPress database.

**DB_USER** must be the database username.

**DB_PASSWORD** must be the correct password.

**DB_HOST** tells WordPress where the database server is located.

On many localhost installations, `DB_HOST` is simply:

“`php
localhost
“`

However, some local environments require a different host value or port configuration.

Don’t change these values randomly. Confirm them against your local development environment.

3. Confirm the Database Actually Exists

Next, open your database management tool.

For many localhost installations, this will be phpMyAdmin.

Look at the database list and check whether your WordPress database exists.

If your `wp-config.php` contains:

“`php
define( ‘DB_NAME’, ‘mywordpress’ );
“`

you should see a database named `mywordpress`.

If it doesn’t exist, WordPress has nowhere to retrieve its content from.

This can happen if you accidentally deleted the database, imported a backup incorrectly, or created WordPress using a different database name.

Don’t create a blank database and expect your old website to reappear. The original WordPress tables and data are required.

4. Check the WordPress Database Tables

If the database exists, open it in phpMyAdmin.

You should see tables such as:

* `wp_posts`
* `wp_users`
* `wp_options`
* `wp_terms`
* `wp_postmeta`
* `wp_comments`

Your table prefix may be different from `wp_`.

For example, `wp-config.php` might contain:

“`php
$table_prefix = ‘abc_’;
“`

In that situation, your tables could begin with `abc_`.

If the database exists but the tables are missing or appear damaged, you may have a database integrity problem rather than a connection configuration problem.

5. Test the Database Connection

If you suspect the credentials are wrong, test them independently of WordPress.

You can use your local database management tool to determine whether the username and password actually work.

If you have changed the MySQL password recently, your WordPress configuration may still contain the old password.

Update `wp-config.php` only after confirming the correct credentials.

Be particularly careful with special characters in passwords. A malformed configuration value can cause PHP to interpret the setting incorrectly.

6. Check the Database Host and Port

Sometimes `localhost` isn’t enough.

Your MySQL server may be configured to use a non-standard port.

For example, MySQL commonly uses port `3306`, although local installations can be configured differently.

If your environment requires a specific port, the database host may need to reflect that configuration.

Don’t assume your setup matches somebody else’s tutorial. Check the database settings in your local development application’s configuration.

This is especially important when another MySQL installation is already running on your computer.

7. Repair a Potentially Corrupted Database

If WordPress can connect to the database but the database itself has problems, repairing the tables may help.

First, make a backup.

Never attempt database repairs without preserving a copy of your existing database when possible.

WordPress also has a built-in database repair facility that can be enabled temporarily through `wp-config.php`:

“`php
define( ‘WP_ALLOW_REPAIR’, true );
“`

After adding this line, visit:

`/wp-admin/maint/repair.php`

You can then use the available repair options.

Once you’ve finished, remove the `WP_ALLOW_REPAIR` line from `wp-config.php`.

Leaving unnecessary repair functionality enabled isn’t a good security practice.

8. Check for a Broken Local MySQL Installation

If MySQL won’t start at all, the problem may not be WordPress.

A corrupted MySQL data directory, conflicting service, incorrect permissions, or damaged configuration can prevent the database server from starting.

Check your local development environment’s error logs.

Look for messages mentioning:

* Port conflicts
* InnoDB errors
* Permission problems
* Missing files
* Database corruption
* Another MySQL process

Avoid deleting MySQL folders simply because a forum post recommends it. Doing so can destroy your databases.

If you have important local projects, back them up before making major changes.

Best Practices and Pro Tips

Preventing the problem is easier than repeatedly repairing it.

Keep regular backups of your WordPress database, particularly before installing major plugins, changing server configurations, or migrating a site.

For local development, document your database name, username, password, port, and local URL. It makes troubleshooting considerably faster.

You should also keep WordPress, PHP, and your local development environment reasonably current. Compatibility problems can appear when one component is significantly older than the others.

Another useful habit is to avoid modifying `wp-config.php` unnecessarily. One incorrect character can prevent WordPress from connecting to the database.

Finally, separate your development and production environments. A localhost installation is excellent for testing, but important production websites should have proper backups, security controls, monitoring, and reliable hosting.

Common Mistakes to Avoid

1. Changing Everything at Once

Don’t modify `DB_NAME`, `DB_USER`, `DB_PASSWORD`, and `DB_HOST` without knowing which value is wrong. Change one thing at a time so you can identify the cause.

2. Forgetting MySQL

Beginners often check Apache and assume everything is running. WordPress also needs its database server.

3. Deleting Database Files

Never delete MySQL data files as a first troubleshooting step. You could turn a recoverable configuration problem into permanent data loss.

4. Ignoring Backups

Always back up your database before attempting repairs, migrations, or major configuration changes.

Conclusion: Get Your Local WordPress Site Working Again

When you need to fix error establishing a database connection on localhost, start with the basics. Check whether MySQL or MariaDB is running, verify the credentials in `wp-config.php`, confirm that the database exists, and then investigate potential corruption or port conflicts.

The important thing is to troubleshoot systematically.

Don’t immediately reinstall WordPress or delete database files. In many cases, the underlying problem is surprisingly simple.

For more practical WordPress troubleshooting guides, fixes, tutorials, and developer-friendly advice, keep WP Fix It Co bookmarked. We’re here to help you solve WordPress problems without unnecessary technical confusion.