BugWP logo BugWP
Back to Community
Home / Community / Core → Installing wordpress

Fixing the 'Error Establishing a Database Connection' During WordPress Installation

68 threads Sep 16, 2025 Core → Installing wordpress

Content

Encountering the "Error establishing a database connection" message while trying to install WordPress is a common and frustrating experience. This guide will walk you through the most frequent causes and their solutions, based on community troubleshooting.

Why This Error Occurs

This error is WordPress's way of saying it cannot communicate with your MySQL or MariaDB database. The installation cannot proceed without this vital connection. The problem is almost always related to incorrect configuration, a missing component, or the database server itself not being ready.

Step-by-Step Troubleshooting Guide

1. Verify Your Database Server is Running

Before troubleshooting anything else, confirm your database server is online. In tools like XAMPP, WAMP, or MAMP, there is typically a control panel where you can visually confirm that the MySQL or MariaDB service has a "Running" status. On a Linux server, you might use a command like sudo systemctl status mysql.

2. Confirm the Database Exists

WordPress cannot create a database; it can only populate an existing one with tables. You must manually create the empty database first using a tool like phpMyAdmin or a command-line interface. Double-check that the database name in your wp-config.php file matches the name you created exactly, including case sensitivity on some systems.

3. Check User Permissions

Creating a database user is not enough. The user must also have been granted all privileges to the specific database you created. A user with access to one database cannot necessarily access another. Log into phpMyAdmin, go to the "User accounts" section, and edit the privileges for your WordPress user to ensure they have full access to the correct database.

4. Review Your wp-config.php Credentials

This is the most common source of problems. The credentials in your wp-config.php file must be perfect.

  • Database Name: Must match the name of the database you created.
  • Username & Password: Must match the database user's login credentials exactly.
  • Database Host: For local installations, this is almost always localhost. However, some local server stacks like MAMP may use a custom port (e.g., localhost:8889 or localhost:3307). If the standard localhost does not work, check your server stack's documentation for the correct MySQL port and specify it in the host field (e.g., localhost:3307).
  • Special Note: Avoid using spaces in your database name or username, as this can require additional formatting and often leads to connection issues.

5. Ensure the Required PHP Extension is Installed

WordPress requires the mysqli PHP extension to communicate with MySQL/MariaDB databases. If you are on a custom server setup (like FreeBSD or a minimal Linux install), you may need to manually install this package (e.g., php74-mysqli or similar) and restart your web server.

6. Try a Manual wp-config.php Setup

If the web-based installer consistently fails, manually create your configuration file.

  1. Locate the wp-config-sample.php file in your WordPress directory.
  2. Open it in a text editor and fill in your database details (DB_NAME, DB_USER, DB_PASSWORD, DB_HOST).
  3. Save the file as wp-config.php (not wp-config-sample.php).
  4. Now, run the WordPress installation by visiting your site URL. It should skip the database setup step and begin creating the admin account.

7. Rule Out Database Server Compatibility

WordPress is designed to work with MySQL or MariaDB. It will not work with Microsoft SQL Server. Furthermore, while it is generally compatible with cloud-managed MySQL services, you may need to adjust specific settings on those platforms, such as disabling SSL enforcement for the initial connection if required.

Need More Help?

If you've worked through all these steps and are still stuck, the best place to get help is the wider WordPress community. Be prepared to share the details of your setup (operating system, local server stack, etc.) and the specific steps you've already taken.

Related Support Threads Support