How to Fix WordPress Error Establishing a Database Connection

The WordPress error establishing a database connection can come from a wrong password, a stopped database service, a full disk, a bad socket, or too many connections. Start with wp-config.php and the logs, then prove the path with the mysql client. Avoid rebooting first; the first useful error is often in the journal.

The first clue is usually not the WordPress error page

I have seen the WordPress message Error establishing a database connection appear after a password change, a stopped MariaDB service, a full filesystem, and a connection limit being reached. The page looks identical each time. The fix is not.

Start with the four values in wp-config.php: database name, username, password, and host. Then check the database service, the logs, and a direct command-line connection. A reboot might make the site return for a moment, but it also throws away useful evidence.

For the file layout and initial WordPress setup, see How to Install WordPress on a VPS: Step-by-Step Guide. The checks here are for a site that worked before and then lost access to its database.

Start here – Confirm the exact error, then separate web server, PHP, and database checks before changing anything.

Confirm what is actually failing

A browser error page, an unavailable WordPress dashboard, and an HTTP 500 response can look much alike. First check whether the web server answers at all.

curl -I https://example.com

A 500 Internal Server Error means the request reached the web server but failed in the application layer. A 502 Bad Gateway points you toward communication between Nginx and PHP-FPM, or another upstream service. Do not focus on MySQL while PHP-FPM is not answering.

Log locations depend on your distribution and web server. Nginx commonly uses /var/log/nginx/error.log; PHP-FPM messages are often in systemd’s journal; Apache commonly writes to /var/log/apache2/error.log.

sudo journalctl -u php8.2-fpm --since "30 minutes ago" --no-pager
sudo tail -n 50 /var/log/nginx/error.log

Replace php8.2-fpm with the service installed on your VPS. On one incident I made the mistake of reading only the browser page. It told me almost nothing. Matching timestamps in the PHP-FPM and database logs narrowed the problem quickly.

mysqli_real_connect(): (HY000/1045) usually points toward authentication or permission trouble. Can't connect to local server through socket suggests a service or socket problem, while Too many connections points toward capacity.

Do this – Compare PHP-FPM, web server, and database entries from the same time window instead of relying on the browser message.

Check the four values in wp-config.php

The file is normally in the WordPress installation directory. A common path is /var/www/html/wp-config.php, but a hosting panel may use a site-specific document root. Do not assume the path.

define( 'DB_NAME', 'wordpress' );
define( 'DB_USER', 'wp_user' );
define( 'DB_PASSWORD', 'strong-and-correct-password' );
define( 'DB_HOST', '127.0.0.1' );

DB_NAME is the database name, DB_USER is the account, DB_PASSWORD is its password, and DB_HOST is the connection target. Keep the quotation marks and semicolons intact. Spaces copied into a password can be surprisingly difficult to spot.

Do not print the password while checking the file.

sudo grep -nE "DB_(NAME|USER|HOST)" /var/www/html/wp-config.php
stat -c '%A %U:%G %n' /var/www/html/wp-config.php

The first command deliberately excludes DB_PASSWORD. The web server account needs to read the file, but the file should not be writable by everyone. chmod 777 is not a database fix; it only replaces one problem with a larger security problem.

DB_HOST deserves special attention. On many Linux installations, localhost makes the client use a Unix socket, while 127.0.0.1 forces a TCP connection. Testing both can show whether the credentials are fine and only the connection method is wrong.

A visually correct configuration file proves very little. The values must match the accounts and databases that exist on the server.

Do this – Match DB_NAME, DB_USER, DB_PASSWORD, and DB_HOST against the actual database server.

Check the database service before restarting it

On Debian and Ubuntu, the service is often named mysql, although MariaDB installations commonly use mariadb.

sudo systemctl status mysql --no-pager
sudo systemctl status mariadb --no-pager

Unit could not be found does not prove that the database is absent. It may simply have another service name.

systemctl list-units --type=service | grep -Ei 'mysql|maria'

If the service is stopped, read the reason before starting it. The journal may distinguish a full filesystem, an invalid configuration, table trouble, or an InnoDB recovery problem.

sudo journalctl -u mysql -b --no-pager -n 100
sudo journalctl -u mariadb -b --no-pager -n 100
df -h
sudo du -sh /var/lib/mysql /var/log/mysql 2>/dev/null

MySQL or MariaDB may need room for redo logs, temporary tables, and binary logs. A full filesystem can prevent the service from starting even when the credentials are perfect.

Look for the first meaningful error, not just the final systemd failure. I have more than once found that the last line was only a consequence of an earlier storage or configuration error.

Do this – Read the database journal and check df -h before restarting MySQL or MariaDB.

Prove the connection from the command line

WordPress, PHP, and the database are separate layers. A direct login using the same account is one of the quickest ways to narrow the fault.

mysql -h 127.0.0.1 -u wp_user -p wordpress

The client asks for the password. Do not put it directly in the command, because it can remain in shell history or appear in process information. After connecting, run:

SELECT 1;
SELECT DATABASE();

ERROR 1045 (28000): Access denied points toward the username, password, source host, authentication method, or privileges. ERROR 1049 (42000): Unknown database means the database name is wrong or missing. ERROR 2002 commonly involves the socket, TCP connection, or service availability.

If the application and database are on different machines, 127.0.0.1 means the application server. It does not mean the database server. Use the database server’s private address or DNS name instead:

mysql -h db.internal.example -P 3306 -u wp_user -p wordpress

For a remote connection, inspect the firewall, MySQL’s bind-address, and the host allowed by the database account. Keep port 3306 on a private network or VPN rather than exposing it to the public internet.

The account’s username and host are evaluated together. That small detail causes many apparently impossible login failures.

Do this – Establish a CLI connection with the same host, user, and database name before changing WordPress files.

Check the MySQL account and its host

'wp_user'@'localhost' and 'wp_user'@'127.0.0.1' can be different account records. The password can be correct while MySQL still rejects the connection because it arrives from another host value.

sudo mysql -e "SELECT User, Host, plugin FROM mysql.user WHERE User='wp_user';"

Inspect the grants for the exact account selected by the connection.

SHOW GRANTS FOR 'wp_user'@'localhost';

When a grant needs correction, name the intended database explicitly:

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

This is narrower than granting access to every database, but save the existing grants before changing production. Check the localhost and 127.0.0.1 records separately if both connection methods are in use.

WordPress updates can require permission to create and alter tables. The application account does not need GRANT OPTION across the whole server. Keep the account limited to its own database.

Authentication plugins can differ between MySQL and MariaDB versions. If an older PHP build cannot use the authentication method selected by the database server, check the installed versions and their documentation before changing the plugin blindly. Upgrading the unsupported PHP component may be safer.

Do this – Compare the selected User, Host, authentication plugin, and grants with the connection WordPress actually makes.

Inspect sockets, ports, DNS, and connection limits

When the CLI login fails, check where the database is listening.

sudo ss -lntp | grep 3306
sudo ss -lxnp | grep -E 'mysql|maria'

The first command looks for a TCP listener. The second looks for a Unix socket. If MySQL listens only on 127.0.0.1:3306, an application on another server cannot connect.

For a remote database, test the path and the name separately:

nc -vz db.internal.example 3306
getent hosts db.internal.example

If nc cannot connect, the problem is below PHP and WordPress: firewall rules, routing, binding, or DNS. If it connects but MySQL returns error 1045, return to authentication and grants.

For Too many connections, inspect current usage and the configured limit:

SHOW STATUS LIKE 'Threads_connected';
SHOW VARIABLES LIKE 'max_connections';

Raising max_connections can make an overloaded VPS worse. Check PHP-FPM worker counts, query duration, connection leaks, and available memory first. The fix may be a slow plugin or a worker configuration rather than a larger number.

A PHP memory or worker problem can also look like a database failure. See How to Fix the WordPress Memory Limit Error for the same log-and-resource approach, and Linux Process Management: Using ps, top, and kill for process inspection. If the response is specifically a gateway error, use How to Fix a 502 Bad Gateway Error.

Do this – Test the socket, TCP port, firewall path, DNS result, and connection count in that order.

Repair only after protecting the data

If the service is running and the account can connect, investigate table access, filesystem errors, and possible corruption. Take a backup first. Repair operations can change table structures or data.

WordPress has a temporary repair mode:

define( 'WP_ALLOW_REPAIR', true );

You can then visit /wp-admin/maint/repair.php. This page may not require normal authentication on every installation, so remove the setting immediately after use. I would use it during a maintenance window, not casually on a busy site.

You can also check the tables from the command line:

mysqlcheck -u wp_user -p wordpress

An OK result means the check completed successfully; it does not prove that the original problem is fixed. Filesystem errors, a full disk, and InnoDB recovery are separate issues. Never delete ibdata1 or redo log files by hand.

Create a logical backup before repairing or removing a table:

mysqldump --single-transaction --routines --triggers wordpress > wordpress-$(date +%F).sql

--single-transaction is generally suitable for an online dump of InnoDB tables. It does not provide the same consistency for MyISAM tables. A dump file sitting on disk is not proof of a usable backup; restore it somewhere separate and test it.

On my Proxmox host, I test risky WordPress and database changes in a disposable VM before touching a customer-facing installation. A MariaDB version difference once made a repair command behave differently than I expected. The VM caught it. A snapshot helped too, but it was not a substitute for a tested database backup.

Do this – Back up the database, check the tables, and investigate storage or recovery without deleting internal database files.

Use caching and plugins as secondary checks

After the database is healthy, an old error page may remain because of page caching, a CDN, or PHP opcode caching. Make a request from a cache-independent client, then clear the relevant cache.

If you can access the WordPress files, temporarily disable plugins by renaming the directory from the site root:

mv wp-content/plugins wp-content/plugins.off

If the error disappears, restore the directory name and enable plugins one at a time. This does not repair the database connection. It helps identify a plugin that opens too many connections or changes database behavior.

If you need WordPress debugging, keep errors out of the browser:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

The log is usually written to wp-content/debug.log. Disable debugging after the investigation or restrict access to the file. SQL statements can contain passwords or personal data.

Do not hide a database problem by deleting random content files. That only makes the next investigation harder.

Do this – Leave cache clearing and plugin changes until service, connectivity, and privilege checks are complete.

What to verify after the site returns

Opening the homepage is not enough. Test the administration panel, save a post, upload media, and check scheduled tasks. Watch disk usage, PHP-FPM messages, and the MySQL or MariaDB error log while doing it.

Verify that the backup job ran and that a restore works. Keep database dumps outside the web root, and check the local copy, remote copy, and retention separately.

Useful alerts include database service state, filesystem usage, active connections, PHP-FPM workers, and the site’s HTTP 5xx rate. When the next alert arrives, compare logs from the affected period before restarting anything.

The same WordPress screen can mean a bad password, a wrong socket, a full disk, or an exhausted connection pool. Test each layer directly. My first command after seeing it now is usually a measurement, not a reboot.

Before You Restart or Repair Anything

• Confirm the exact browser or HTTP error.
• Read the PHP-FPM, web server, and database logs.
• Check all four database values in wp-config.php.
• Verify the database service and available disk space.
• Test the connection with the mysql client.
• Inspect the account host and granted privileges.
• Create and test a backup before repairing tables.

Frequently Asked Questions

Sources

• WordPress Documentation – Editing wp-config.php — wordpress.org
• MySQL 8.0 Reference Manual — dev.mysql.com
• WordPress Developer Resources – wp-config.php — developer.wordpress.org