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_PASSWORDorDB_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.1and a socket path are not interchangeable. - Corrupted tables, which usually break wp-admin or single pages rather than the whole connection.
Quick-fix checklist
- Open
wp-config.phpand copy the four values:DB_NAME,DB_USER,DB_PASSWORD,DB_HOST. Look for stray spaces and smart quotes. - Test those exact values outside WordPress with the small PHP file or the
mysqlcommand below. The error code tells you which cause you have. - If you have root, check the database service:
systemctl status mariadborsystemctl status mysql. - If the server stopped, look for out-of-memory kills:
sudo dmesg -T | grep -i -E "killed process|out of memory". - On cPanel, open MySQL Databases, check the user is listed under Privileged Users for the database, and reset its password if unsure.
- 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:
| Code | Message (shortened) | Likely cause |
|---|---|---|
| 1045 | Access denied for user ... (using password: YES) | Wrong username or password, or the user is defined for a different host |
| 1044 | Access denied for user ... to database ... | Login works, but the user has no privileges on that database |
| 1049 | Unknown database | Wrong DB_NAME, often a missing cPanel prefix |
| 2002 | No such file or directory / Connection refused | From PHP: server stopped, wrong socket path, or nothing listening on that IP and port |
| 2002 / 2003 | Can'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 / 1226 | Too many connections / max_user_connections | Server-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 )
- WordPress Developer Resources: Common WordPress errors: Error establishing database connection
- WordPress Developer Resources: wp-config.php: database settings, DB_HOST and WP_ALLOW_REPAIR
- PHP Manual: mysqli_driver::$report_mode
- cPanel Docs: MySQL Databases
- MySQL Reference Manual: Connecting to the server: localhost, socket and TCP
- MySQL Reference Manual: Troubleshooting problems connecting to MySQL
- MySQL Reference Manual: Too many connections
- MySQL Reference Manual: REPAIR TABLE: supported storage engines