How to Fix the “Error Establishing a Database Connection” in WordPress

Few scenarios are more critical for a WordPress site administrator than encountering the “Error Establishing a Database Connection.” This fatal error halts all communication between your WordPress core files and the MySQL or MariaDB database, rendering your website’s front end and the /wp-admin backend completely inaccessible. When this connection fails, your posts, pages, settings, and user data cannot be retrieved.

While severe, this error is typically resolvable through systematic troubleshooting. The following flowchart provides a linear diagnostic path, which we will elaborate on in a detailed, step-by-step manner.

Step 1: Verify the Database Service Status

The most fundamental check is to ensure the database daemon process is running on your server.

Action:

• If you have SSH or command-line access, check the service status:

  bash

  sudo systemctl status mysql
  # or
  sudo systemctl status mariadb

• If the service is inactive, start it:

  bash

  sudo systemctl start mysql

• For users on shared hosting or control panels (e.g., cPanel, Plesk), access your hosting dashboard. Navigate to the “Services,” “Databases,” or “MySQL” section to verify and manage the service state.

Step 2: Validate Database Credentials in wp-config.php

Incorrect connection parameters in WordPress’s primary configuration file are a common cause.

Action:
Access your site’s root directory via FTP/SFTP or your host’s file manager. Locate and edit the wp-config.php file. Scrutinize and confirm these four constants match the details provided by your hosting service:

define('DB_NAME', 'database_name_here');    // The exact database name
define('DB_USER', 'username_here');         // The exact database username
define('DB_PASSWORD', 'password_here');     // The correct password for the above user
define('DB_HOST', 'localhost');             // Usually 'localhost' or '127.0.0.1'

Important: If 'localhost' fails, try replacing it with '127.0.0.1' or the specific socket path (e.g., 'localhost:/path/to/mysql.sock').

Step 3: Confirm Database User Permissions and Accessibility

Credentials may be correct, but the user might lack the necessary privileges or the ability to connect from localhost.

Action:

1. Access your database management interface, typically phpMyAdmin, provided in your hosting control panel.

2. Attempt to log in using the DB_USER and DB_PASSWORD from your wp-config.php.

3. If login fails: The credentials are invalid. You must reset the database user’s password via your host’s database management tools or command line.

4. If login succeeds but the database is inaccessible: The user lacks privileges. In phpMyAdmin, select the user, click Edit Privileges, navigate to the Database-specific privileges section, select your WordPress database, and ensure ALL PRIVILEGES are granted.

Step 4: Enable WordPress Debugging to Capture the Specific Error

When basic checks pass, you must force WordPress to reveal the underlying technical error.

Action:

1. Edit wp-config.php again.

2. Locate the line define('WP_DEBUG', false);.

3. Insert the following code block immediately before the line that says /* That's all, stop editing! Happy publishing. */:

   php

   // Enable debugging to a log file
   define('WP_DEBUG', true);
   define('WP_DEBUG_LOG', true);      // Saves errors to /wp-content/debug.log
   define('WP_DEBUG_DISPLAY', false); // Prevents errors from displaying on site
   @ini_set('display_errors', 0);

4. Save the file and attempt to reload your website. This generates a debug.log file in /wp-content/. Download this file—it contains the precise MySQL or PHP error message.

Step 5: Apply the Targeted Solution Based on the Logged Error

The error message in debug.log or your server’s error log dictates the exact fix.

• Solution for caching_sha2_password Authentication Error: This occurs with PHP versions incompatible with MySQL 8.0’s default authentication plugin.

  1. Access MySQL via command line or phpMyAdmin’s SQL tab with a privileged account (e.g., root).

  2. Execute the following SQL command, replacing the placeholders:

     sql

     ALTER USER 'DB_USER'@'DB_HOST' IDENTIFIED WITH mysql_native_password BY 'NewStrongPassword123!';
     FLUSH PRIVILEGES;

  3. Immediately update the DB_PASSWORD value in wp-config.php with the new password.

• Solution for Server Memory Exhaustion: Check your server logs (/var/log/syslog or /var/log/messages) for “Out of memory” or “Killed process mysqld” entries, indicating the OOM (Out-Of-Memory) killer terminated MySQL.

  1. This is a critical server resource issue. Immediately contact your hosting provider to upgrade your plan (recommended minimum: 4GB RAM for dynamic sites).

  2. As a temporary mitigation, you can optimize your database by removing unnecessary data, but a resource upgrade is the definitive fix.

• Solution for Plugin or Theme Conflict: If the debug.log shows no direct database error, a corrupted script may be breaking the connection.

  1. Via FTP/SFTP, rename the /wp-content/plugins directory to plugins.deactivated.

  2. Reload your site. If it loads (without functionality), a plugin is the cause.

  3. Rename the folder back to plugins. Then, rename individual plugin folders one by one, checking the site after each, to identify the faulty plugin.

  4. Repeat the process for the /wp-content/themes/ folder to test your active theme by switching to a default theme like Twenty Twenty-Six.

Final Steps and Proactive Maintenance

• Disable Debugging: After resolving the issue, set define('WP_DEBUG', false); and delete the /wp-content/debug.log file to prevent exposing sensitive information.

• Implement Regular Backups: Use a reliable plugin like UpdraftPlus or your host’s automated backup solution to maintain recent backups of both your files and database.

• Maintain Updates: Consistently update WordPress core, themes, and plugins to their latest stable versions to mitigate security vulnerabilities and compatibility bugs.

• Engage Your Hosting Support: If the problem persists after these steps, provide them with the specific error logs. They can investigate advanced server-side issues like corrupted database tables, firewall rules blocking port 3306, or disk space exhaustion.