Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

WordPress "Error establishing a database connection": check wp-config, then the database server

Technical article
Troubleshooting

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

  1. A page that needs the database, not a cached page, loads normally. Log in to /wp-admin/ and open a post.
  2. mysqladmin against the host in DB_HOST returns exit status 0, and the manual login from step 3 works with no error.
  3. The database server's log shows no new connection errors from the web server's address.
  4. If you enabled the repair feature, the WP_ALLOW_REPAIR line is removed and php -l wp-config.php reports 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_HOST fails in exactly this way.

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 ping uses 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