About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.
This message means WordPress could not connect to its database. The WordPress documentation says it "is usually caused by an error in your wp-config.php file", so check the four database details first. If they are right, the database server may be stopped, unreachable, or full of connections. You can tell which by logging in to the database yourself, outside WordPress, with the same details.
What the error means
WordPress reads four database settings from wp-config.php. The installation guide lists them: DB_NAME (the database), DB_USER (the account), DB_PASSWORD (its password) and DB_HOST. For DB_HOST the guide says: "usually localhost, but not always". It adds: "If a port, socket, or pipe is necessary, append a colon (:) and then the relevant information to the hostname."
The Common WordPress Errors page says the message "means that there is a problem with the connection to your database and there could be a number of reasons for this". It lists a wrong name, username, password or host in wp-config.php, and web host problems: "Your database has met its quota and has been shut down" and "The server is down." It also notes a compromised site as a possibility if the configuration and the host both check out.
The MySQL manual explains the connection route that matters when DB_HOST is localhost: "On Unix, MySQL programs treat the host name localhost specially, in a way that is likely different from what you expect compared to other network-based programs: the client connects using a Unix socket file." A name or address such as 127.0.0.1 makes "a TCP/IP connection to the local server". So localhost and 127.0.0.1 are two different routes to the same server, and one can work while the other fails.
Likely causes
| Cause | What you see | How to confirm |
|---|---|---|
A wrong database name, user or password in wp-config.php |
The error began after a migration, a restore or a password change | A manual login with the same details fails with an access error |
A wrong DB_HOST |
The site moved to a new server and the database stayed behind, or the reverse | mysqladmin ping to that host fails, or answers from a different server |
| The database server is stopped | Every site that uses it fails together | systemctl status shows the service not running |
| The server does not accept the route used | localhost fails, 127.0.0.1 works, or a remote host is refused |
The MySQL manual lists skip_networking, a restricted bind_address, a changed socket and a firewall |
| All connections are in use | The error comes and goes under load | See MySQL ERROR 1040 "Too many connections": find who holds them before raising max_connections |
| A quota or damaged tables on hosted databases | The host reports a quota, or the log or the host points at damaged tables | The host's control panel, or the WordPress repair feature described below |
Prove the cause before changing anything
All of these are read-only.
1. Read the four settings. Open wp-config.php in the site's root and note DB_NAME, DB_USER and DB_HOST. Do not paste DB_PASSWORD into tickets or chat.
2. Ask the server whether it is running.
mysqladmin -u wpuser -p -h 127.0.0.1 ping
Use your own account and the host from DB_HOST. With -p and no value, the client prompts for the password, which the MySQL manual says "is more secure than giving the password on the command line". The mysqladmin manual defines the result: "The return status from mysqladmin is 0 if the server is running, 1 if it is not. This is 0 even in case of an error such as Access denied, because this means that the server is running but refused the connection, which is different from the server not running." Read the exit status with echo $? straight after the command.
A status of 1 means nothing answered on that route. A status of 0 with an access error means the server is running and the credentials or the account's allowed host are wrong.
3. Log in the way WordPress does.
mysql -h 127.0.0.1 -u wpuser -p wpdb
This follows the MySQL manual's form mysql -h localhost -u myname -p mydb. If it connects, the account, password and database name are right for that host. Repeat with -h localhost if DB_HOST is localhost: that uses the socket route.
4. Check the service. Replace UNIT with the name of the database service on your system; the name depends on how the database was installed.
systemctl status UNIT
journalctl -u UNIT -n 50 --no-pager
journalctl -u selects a unit, -n limits the number of lines and --no-pager prints without paging. Read why the service stopped before you start it.
5. If the database is on another host, run step 2 from the web server with -h set to that host and --port=3306, one of the forms the MySQL manual shows (mysqladmin -h host_ip version). The manual's checklist for refused connections: make sure the server "has not been configured to ignore network connections", check skip_networking and bind_address, and check "that there is no firewall blocking access to MySQL" on port 3306 by default.
Fix
Disruptive step: every wp-config.php change takes effect on the next request, and a typo breaks the whole site. Save the file first, outside the web root, because it holds DB_PASSWORD and a copy inside the site folder can be downloaded as plain text. Check its syntax before and after:
cp -p wp-config.php /root/wp-config.php.2026-11-20
php -l wp-config.php
The PHP manual describes -l as "Syntax check only (lint)". To back out of any edit below, restore the saved file under the name you saved it, then check it:
cp -p /root/wp-config.php.2026-11-20 wp-config.php
php -l wp-config.php
Wrong name, user, password or host
Correct the value in wp-config.php so it matches the account that worked in step 3. If the account's password was changed in the database, put the same value in the file. To change an account's password on the server, use your database's normal account-management procedure; the WordPress page says only that you "could try resetting your MySQL password manually". After a migration, set DB_HOST to the new database host, with :port appended if the database does not use the default port, as the installation guide describes.
If the error then changes to an access-denied message, the server is reachable and the account is the problem. Continue with MySQL ERROR 1045 (28000) "Access denied for user": which account the server matched.
Server stopped
Disruptive step: starting the database affects every website that uses it. If the journal shows a disk-full or corruption error, fix that first, because the service may stop again for the same reason. To back out of a start you did not intend, run systemctl stop UNIT.
If systemctl status shows the service stopped and the journal shows why, start it:
systemctl start UNIT
Route or firewall
If localhost fails and 127.0.0.1 works, or the reverse, use the route that works in DB_HOST, or correct the socket as described in MySQL ERROR 2002 "Can't connect to local MySQL server through socket": is it running, and which socket. For a remote database, the server must accept network connections, and the MySQL manual's access-control page says the server accepts a connection only if "the client host name and user name match the Host and User columns in some user table row", so the account must exist for the web server's host.
Too many connections
If the error comes and goes under load, follow MySQL ERROR 1040 "Too many connections": find who holds them before raising max_connections.
Damaged tables
The Editing wp-config.php page describes an automatic repair feature: add define( 'WP_ALLOW_REPAIR', true ); to wp-config.php; the script "can be found at {$your_site}/wp-admin/maint/repair.php". Take a database backup first.
Risk: the page warns: "When enabled, a user does not need to be logged in to access the functionality". Anyone who knows the address can run it while the line is present. It "should only be enabled if needed and disabled once the issue is solved". To back out, remove the line, or restore the saved /root/wp-config.php.2026-11-20, and run php -l wp-config.php.
Example (illustrative): app.example.com is moved from an old server to web01, and the database stays on db01 (203.0.113.20). The site shows the error. wp-config.php still has DB_HOST set to localhost. On web01, mysqladmin -u wpuser -p -h localhost ping exits with status 1, because no MySQL server runs on web01. The same command with -h 203.0.113.20 exits with status 0. The administrator saves wp-config.php, sets DB_HOST to 203.0.113.20, runs php -l wp-config.php, and reloads the site. It now reports an access-denied message from the database, which means the account is not yet allowed from web01; that is fixed on db01 using the MySQL ERROR 1045 steps.
Confirm the fix
- A page that needs the database, not a cached page, loads normally. Log in to
/wp-admin/and open a post. mysqladminagainst the host inDB_HOSTreturns exit status 0, and the manual login from step 3 works with no error.- The database server's log shows no new connection errors from the web server's address.
- If you enabled the repair feature, the
WP_ALLOW_REPAIRline is removed andphp -l wp-config.phpreports no syntax errors.
What to watch afterwards
- Monitor the database service and a real database-backed page, not only the home page, so an outage is seen before visitors see it.
- Record the account, host and database name for each site in one place, and update the record after every migration.
- Watch connection counts against the server's limit during busy periods.
- Test restores of the database separately from file restores. A restored site with the wrong
DB_HOSTfails in exactly this way.
Read next
Related articles you may want next.
- TroubleshootingMySQL ERROR 1045 (28000) "Access denied for user": which account the server matchedMySQL ERROR 1045 (28000) Access denied for user? Read the user, host and 'using password' text, find the account the server matched, then fix it.Read article
- TroubleshootingMySQL ERROR 2002 "Can't connect to local MySQL server through socket": is it running, and which socketMySQL ERROR 2002 'Can't connect to local MySQL server through socket'? Check mysqld is running, find the real socket path, and fix the client.Read article
- TroubleshootingMySQL ERROR 1040 "Too many connections": find who holds them before raising max_connectionsMySQL ERROR 1040 Too many connections? Use the reserved admin connection to see who holds them, fix the cause, then raise max_connections safely.Read article
Risks and limits
- These commands have not been run or lab-tested.
- The MySQL behaviour above is from the MySQL 8.4 manual. MariaDB uses similar client tools, but its behaviour is not covered by these pages.
mysqladmin pinguses the credentials you give it. A passing ping does not prove that WordPress's own account is correct. Step 3 tests that.- The unit name, the socket path and the default port can differ on your server, and a hosting provider's control panel may manage the database service for you.
- A site that has been tampered with can show the same message. The WordPress page suggests scanning the site if the configuration and the host are both correct.
Sources
- Common WordPress Errors — WordPress Developer Resources, last updated October 14, 2026, accessed 20 November 2026
- How to Install WordPress — WordPress Developer Resources, last updated October 14, 2026, accessed 20 November 2026
- Editing wp-config.php — WordPress Developer Resources, last updated October 14, 2026, accessed 20 November 2026
- MySQL 8.4 Reference Manual: Connecting to the MySQL Server Using Command Options — Oracle, no date shown, accessed 20 November 2026
- MySQL 8.4 Reference Manual: mysqladmin — Oracle, no date shown, accessed 20 November 2026
- MySQL 8.4 Reference Manual: Can't connect to [local] MySQL server — Oracle, no date shown, accessed 20 November 2026
- MySQL 8.4 Reference Manual: Access Control, Stage 1: Connection Verification — Oracle, no date shown, accessed 20 November 2026
- systemctl — systemd 262 documentation, no date shown, accessed 20 November 2026
- journalctl — systemd 262 documentation, no date shown, accessed 20 November 2026
- PHP manual: Command line options — PHP documentation, no date shown, accessed 20 November 2026
This article was originally published on .