Talk to the NOC, IST hours — +91 75994 50220 support@bigdomainhost.com
Guide

How to fix “Error establishing a database connection” in WordPress

This WordPress error means PHP could not connect to the site's MySQL or MariaDB database. This guide shows how to test the credentials, read the error code and fix each of the six usual causes.

Short answer: WordPress shows “Error establishing a database connection” when it cannot log in to its MySQL or MariaDB database. The usual causes are wrong DB_NAME, DB_USER, DB_PASSWORD or DB_HOST values in wp-config.php, a stopped or out-of-memory database server, a user without privileges, a connection limit, or the wrong host after a migration. Test the credentials with a small PHP file to find which.

What "Error establishing a database connection" means

WordPress shows "Error establishing a database connection" when PHP cannot open a working connection to the MySQL or MariaDB database named in wp-config.php. Every page needs the database, so the whole site, wp-admin included, shows the same short message.

Every cause looks the same to visitors. WordPress shows the underlying MySQL error only when WP_DEBUG is true and errors are displayed, so your job is to find which of these you have:

  • Wrong credentials in DB_NAME, DB_USER, DB_PASSWORD or DB_HOST.
  • The database server is down, often killed for lack of memory.
  • The user exists but has no privileges on that database.
  • Too many connections, either server-wide or for your account.
  • The wrong host after a migration: localhost, 127.0.0.1 and a socket path are not interchangeable.
  • Corrupted tables, which usually break wp-admin or single pages rather than the whole connection.

Quick-fix checklist

  1. Open wp-config.php and copy the four values: DB_NAME, DB_USER, DB_PASSWORD, DB_HOST. Look for stray spaces and smart quotes.
  2. Test those exact values outside WordPress with the small PHP file or the mysql command below. The error code tells you which cause you have.
  3. If you have root, check the database service: systemctl status mariadb or systemctl status mysql.
  4. If the server stopped, look for out-of-memory kills: sudo dmesg -T | grep -i -E "killed process|out of memory".
  5. On cPanel, open MySQL Databases, check the user is listed under Privileged Users for the database, and reset its password if unsure.
  6. Only if the connection works but tables are damaged, use the WordPress repair page, then remove the setting that enables it.

Test the credentials with a small PHP file

This separates a WordPress problem from a database problem. Create a file with a hard-to-guess name, such as dbtest-7f3k.php, in the same folder as wp-config.php, paste in your four values (use your DB_HOST value in place of localhost if it differs) and open it in the browser:

<?php
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
try {
    $db = new mysqli('localhost', 'DB_USER_HERE', 'DB_PASSWORD_HERE', 'DB_NAME_HERE');
    echo 'Connected. Server version: ' . $db->server_info;
} catch (mysqli_sql_exception $e) {
    echo 'Failed (' . $e->getCode() . '): ' . $e->getMessage();
}

Since PHP 8.1, mysqli throws a mysqli_sql_exception on failure by default; the mysqli_report() line makes older PHP versions behave the same way. Delete the file as soon as you have the result. It holds your database password in plain text.

What the code means:

CodeMessage (shortened)Likely cause
1045Access denied for user ... (using password: YES)Wrong username or password, or the user is defined for a different host
1044Access denied for user ... to database ...Login works, but the user has no privileges on that database
1049Unknown databaseWrong DB_NAME, often a missing cPanel prefix
2002No such file or directory / Connection refusedFrom PHP: server stopped, wrong socket path, or nothing listening on that IP and port
2002 / 2003Can't connect to local server through socket / Can't connect to server on '127.0.0.1'The same failures as reported by the mysql command-line client
1040 / 1203 / 1226Too many connections / max_user_connectionsServer-wide or per-user connection limit reached

If the test connects but WordPress still fails, the values in wp-config.php differ from what you typed, or a duplicate define() earlier in the file is the one in effect (PHP keeps the first definition of a constant).

Check from the command line

With SSH access, the mysql client (mariadb on newer MariaDB) gives the same answer faster:

mysql -u DB_USER -p -h localhost DB_NAME -e "SELECT 1;"
mysql -u DB_USER -p -h localhost -e "SHOW GRANTS FOR CURRENT_USER();"

The second command lists what the user is allowed to do. You want a line granting privileges on `DB_NAME`.*, not only USAGE, which means no rights at all. On cPanel the underscore appears escaped, as `cpuser\_wpdb`.*.

Cause 1: wrong values in wp-config.php

The four settings must match an existing database user exactly:

define( 'DB_NAME', 'cpuser_wpdb' );
define( 'DB_USER', 'cpuser_wpuser' );
define( 'DB_PASSWORD', 'your-password' );
define( 'DB_HOST', 'localhost' );

On cPanel, database prefixing adds your account username and an underscore to every database and user name, so wpdb becomes cpuser_wpdb. Leaving the prefix off gives error 1049 or 1045. Inside the single quotes, a password containing ' must be written as \' and a backslash as \\, or WordPress reads a different password or the line breaks.

Cause 2: wrong host after a migration

DB_HOST defaults to localhost, which is right on most servers. But the hosts mean different things. On Unix, MySQL and MariaDB clients treat localhost as "use the Unix socket file", while 127.0.0.1 forces a TCP connection, to port 3306 unless you give another. A site moved from a server where the socket was in the default place to one where it is not, or where MySQL listens only on TCP, can fail on one form and work with the other.

WordPress accepts a port or socket after a colon:

define( 'DB_HOST', '127.0.0.1:3307' );
define( 'DB_HOST', 'localhost:/run/mysqld/mysqld.sock' );

Find the real socket path with SELECT @@socket; and the port with SELECT @@port; from a working mysql session. Database users are also tied to a host: 'wpuser'@'localhost' is a different account from 'wpuser'@'127.0.0.1', so switching DB_HOST can turn a working login into error 1045. Our website migration guide covers the other steps to check after a move.

Cause 3: the database server is down or out of memory

On a VPS or dedicated server, check the service first. MariaDB's unit is mariadb; MySQL on Ubuntu and Debian uses mysql, and on AlmaLinux mysqld:

sudo systemctl status mariadb
sudo journalctl -u mariadb -n 50 --no-pager
sudo systemctl start mariadb

If it is stopped, find out why before restarting it again and again. The journal shows startup errors such as a bad option in my.cnf or a full disk (df -h). Once it is up, SELECT @@log_error; shows where the server writes its own error log.

The most common reason a database stops by itself on a small server is the kernel's out-of-memory killer, which usually picks the process using the most memory. If dmesg shows mysqld or mariadbd was killed, lower innodb_buffer_pool_size, reduce PHP worker counts, add swap or move to a bigger plan. Our guide on how much RAM a VPS needs helps with sizing.

Cause 4: the user lacks privileges

A user that can log in but gets error 1044 has not been added to the database. In cPanel, open MySQL Databases, go to Add User To Database, choose the user and database, click Add, tick ALL PRIVILEGES and click Make Changes. On your own server, as the database root user (here the database is wordpress and the user wpuser; the host part must match how WordPress connects):

GRANT ALL PRIVILEGES ON `wordpress`.* TO 'wpuser'@'localhost';

To reset a forgotten password in cPanel, find the user under Current Users, choose Change Password, then put the same new password in wp-config.php. On your own server, use ALTER USER 'wpuser'@'localhost' IDENTIFIED BY 'new-password'; and update wp-config.php to match.

Cause 5: too many connections

MySQL and MariaDB refuse new clients with Too many connections once max_connections is reached. On shared hosting a per-user limit usually applies first. Raising the limit is rarely the real fix: connections pile up because queries are slow, a plugin opens extra connections, or bots flood uncached pages. Check what is running with SHOW FULL PROCESSLIST;, then fix slow queries, enable page caching and block abusive crawlers.

Cause 6: corrupted tables

A crashed table more often breaks part of the site than the connection itself, but it can stop WordPress loading, sometimes with the message "One or more database tables are unavailable". Back up the database first (for example with mysqldump or phpMyAdmin's Export), then add this line to wp-config.php above the "stop editing" comment:

define( 'WP_ALLOW_REPAIR', true );

Open https://yoursite/wp-admin/maint/repair.php and run the repair. The page works without logging in, so remove the line as soon as you are done. cPanel's Check Database and Repair Database tools, or mariadb-check -u DB_USER -p --auto-repair DB_NAME (mysqlcheck on MySQL), do the same job. Note that REPAIR TABLE, which all of these use, works on MyISAM, Aria, ARCHIVE and CSV tables, not InnoDB, the default engine for WordPress tables today, so a damaged InnoDB table usually means restoring from a backup.

Fixing this on Bigdomainhost

On Web & cPanel hosting and WordPress hosting, databases are MySQL or MariaDB, managed in cPanel and phpMyAdmin, and DB_HOST stays localhost. Remote database access is off by default and is enabled per IP. Web & cPanel plans allow 25 concurrent MySQL connections, so a "too many connections" error there usually points to slow queries or uncached traffic. Daily backups let you restore a database yourself from the panel if tables are beyond repair.

On a KVM VPS you have root access, so every systemctl, journalctl and mysql command above works as written, and the out-of-band console in the panel gets you in even if SSH is down. Take a snapshot before repairing tables; the snapshots and backups docs explain how. If you are stuck, call +91 75994 50220 during IST hours, WhatsApp the same number any time, or email support@bigdomainhost.com with your domain and the error code from the test file.

Sources (checked )

Answers

Frequently asked questions

Still unsure? Call +91 75994 50220 or write to support@bigdomainhost.com — a human replies in IST hours.

What does “Error establishing a database connection” mean?

It means WordPress could not connect to the MySQL or MariaDB database listed in wp-config.php. Either the database name, username, password or host is wrong, the user lacks rights on the database, the database server is stopped or overloaded, or the connection limit has been reached. Your files and content are usually still intact.

Is this error my fault as a visitor?

No. The website cannot reach its own database, which is a problem on the server side. Clearing your browser cache, switching browser or changing network will not fix it. Try again later, and if the site matters to you, let the owner know the time you saw the error.

Should DB_HOST be localhost or 127.0.0.1?

Use whatever your host specifies; on most servers, including cPanel hosting, it is localhost. On Linux, localhost makes the client use the Unix socket file, while 127.0.0.1 forces a TCP connection. If one fails after a migration, try the other, or add the correct port or socket path after a colon.

Is it safe to leave WP_ALLOW_REPAIR on?

No. The repair page at /wp-admin/maint/repair.php can be opened by anyone without logging in while the setting is active, and WordPress documentation says to disable it once the issue is solved. Back up the database, run the repair, then delete the define line from wp-config.php straight away.

How do I reset the WordPress database password in cPanel?

Open MySQL Databases in cPanel, find the user under Current Users and choose Change Password. Set a new password, then update DB_PASSWORD in wp-config.php to match exactly. While there, check the user is listed under Privileged Users for the right database, and add it with ALL PRIVILEGES if it is not.

Support that picks up the phone.

In IST hours, in Hindi or English, and WhatsApp replies fastest at any time. Sales, migration and emergencies all reach the same engineers. No offshore queue, no 48-hour first reply.

Need cPanel or WHM with the ports already sorted?

Web & cPanel hosting comes with cPanel ready to log in to, reseller hosting adds white-label WHM, and a KVM VPS can have cPanel & WHM pre-installed. Call +91 75994 50220 or email support@bigdomainhost.com.