The WordPress message “Error establishing a database connection” means WordPress cannot successfully connect to its configured MySQL or MariaDB database. Start by checking whether the host and database service are available, then verify DB_NAME, DB_USER, DB_PASSWORD, and DB_HOST in the correct wp-config.php. Test the connection independently before attempting any database repair. This order distinguishes a typo or permission problem from an outage, quota limit, corruption, migration mistake, or security incident.
Antihost offers managed WordPress hosting with free migration, one-click staging and a 14-day free trial.
What the error means
WordPress loads pages by reading settings, posts, users, plugin data, and other content from MySQL or MariaDB. The error appears when that connection cannot be established. The browser message is deliberately generic: it does not tell you whether authentication failed, the hostname is wrong, the database service is stopped, the account has reached a limit, or tables are damaged.
As an Amazon Associate I earn from qualifying purchases.
The failure may take down the entire site, including /wp-admin, or affect only some requests. An error that began during a new installation usually indicates incorrect database details or an incorrectly created database user. An error immediately after migration commonly means that the old database name, password, hostname, port, or permissions were copied to the new server.
Intermittent failures are a different clue. A permanently wrong password normally fails consistently; errors that appear only during traffic spikes often indicate exhausted connections, a crashing database service, disk exhaustion, expensive queries, or hosting-account resource limits.
#1 Best Overall
- Easily store and access 2TB to content on the go with the Seagate Portable Drive, a USB external hard drive
- Designed to work with Windows or Mac computers, this external hard drive makes backup a snap just drag and drop
- To get set up, connect the portable hard drive to a computer for automatic recognition no software required
- This USB drive provides plug and play simplicity with the included 18 inch USB 3.0 cable
- The available storage capacity may vary.
WordPress lists configuration mistakes, a host or database server outage, a reached database quota, damaged tables, and possible compromise among the causes: WordPress common errors documentation.
Do these checks before changing anything
- Record the evidence. Note the exact message, the first failure time, whether every page fails, and whether failures are intermittent.
- Identify the last change. Ask whether a hosting move, database-password reset, DNS or domain change, PHP/MySQL upgrade, plugin or theme installation, backup restoration, or resource warning happened immediately beforehand.
- Confirm a backup. If the database is still accessible, create and download a database backup before repair. Keep a copy of the current files as well.
- Download the current configuration. Save the correct WordPress root’s
wp-config.phpbefore editing it. - Protect credentials. Never paste database passwords into support tickets, screenshots, public code snippets, shell history, or logs.
- Do not start with destructive actions. Do not delete tables, reinstall WordPress, or repeatedly run repair commands until you know whether the server can be reached.
WordPress specifically recommends a backup before database repair: its troubleshooting guidance.
Free tools Windows power users keep installed
One-click scans. No signup required.
Check the hosting service first
Before resetting a password, open the provider’s status page and control panel. Look for a database incident, suspended account, storage quota warning, or a changed database hostname or port. Check disk space, inode usage, RAM, CPU, process limits, and connection limits if your plan exposes them. On shared hosting, throttling or a full account can make a healthy database appear unavailable.
Ask the host to verify that the MySQL/MariaDB service is running, that this account can connect, and that the database and PHP error logs contain no outage or resource-limit event at the failure time. WordPress identifies a down server and a reached database quota as host-side causes and advises contacting the provider when they apply.
You can send this support request:
My WordPress site displays “Error establishing a database connection.” Please confirm whether the database server is operational, whether this account has exceeded storage or connection limits, and whether the database username, password, hostname, or port recently changed. Please check the database-server and PHP error logs for this domain and timestamp.
Verify wp-config.php
Open the file in the WordPress installation that the web server actually serves. The relevant section looks like this, with example values only:
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsdefine( 'DB_NAME', 'database_name' );
define( 'DB_USER', 'database_username' );
define( 'DB_PASSWORD', 'database_password' );
define( 'DB_HOST', 'database_hostname' );
$table_prefix = 'wp_';Check each database constant
DB_NAME: Match the database name exactly as shown in the hosting panel or server configuration.DB_USER: Match the database user, including any hosting-account prefix.DB_PASSWORD: Use the current password, not an older value stored in a password manager.DB_HOST: Use the host’s documented hostname, port, or socket format.localhostis not universal.
Also check that the values belong to this installation, that the file has valid PHP syntax, and that it contains no smart quotes, missing semicolons, pasted markup, or accidental edits to unrelated constants. If WordPress connects but reports missing tables or behaves like a fresh installation, compare $table_prefix with the actual table names.
Rank #2
- Easily store and access 5TB of content on the go with the Seagate portable drive, a USB external hard Drive
- Designed to work with Windows or Mac computers, this external hard drive makes backup a snap just drag and drop
- To get set up, connect the portable hard drive to a computer for automatic recognition software required
- This USB drive provides plug and play simplicity with the included 18 inch USB 3.0 cable
- The available storage capacity may vary.
Safe password-reset procedure
- Reset or change the database-user password in the hosting panel or database server.
- Update
DB_PASSWORDin the correctwp-config.php. - Save the file without changing unrelated settings.
- Test both the front end and
/wp-admin. - Remove or rotate temporary access credentials.
- Update deployment secrets, scheduled jobs, containers, and environment variables that also use the database.
A password reset alone may not help if the user is no longer assigned to the database, the grants are missing, or the provider requires a different hostname or port.
Confirm the database user and permissions
In the hosting control panel or database administration tool, verify that the database exists, the named user exists, and that the user is assigned to that database with the required privileges. A user can have the correct password and still receive an authentication error when the server sees a different user-host combination or no grants.
After a migration, confirm that the import completed and that the destination user was created and assigned. Do not assume that opening phpMyAdmin proves WordPress is configured correctly: phpMyAdmin may use another username, host, database, or socket.
Recommended Free Tools
Test the connection outside WordPress
An independent connection test is the quickest way to separate WordPress configuration from a database-server problem.
Use WP-CLI
From the WordPress directory, run:
cd /path/to/wordpress
wp db cli --debugwp db cli opens a MySQL console using the credentials loaded from wp-config.php. The --debug option provides more diagnostic detail. For a remote or multisite installation, specify the intended path and site:
wp --path=/path/to/wordpress --url=https://example.com db cli --debugSee the command reference for supported options such as --path, --url, --ssh, and --debug: WP-CLI db cli.
If the connection succeeds, check the database:
wp db checkUse the MySQL client
Administrators can test with:
mysql -u database_username -p -h database_hostname database_nameEnter the password at the prompt instead of putting it in the command, where shell history or process listings could expose it.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Rank #3
- Easily store and access 1TB to content on the go with the Seagate Portable Drive, a USB external hard drive.Specific uses: Personal
- Designed to work with Windows or Mac computers, this external hard drive makes backup a snap just drag and drop. Reformatting may be required for Mac
- To get set up, connect the portable hard drive to a computer for automatic recognition no software required
- This USB drive provides plug and play simplicity with the included 18 inch USB 3.0 cable
- The available storage capacity may vary.
Interpret the result
| Observed result | Likely class | Next action |
|---|---|---|
| Access denied | Wrong password, username, user-host mapping, or privileges | Reset the password and verify the user is assigned to the database with appropriate grants |
| Unknown host | Wrong DB_HOST, DNS failure, container service-name error, or unavailable internal hostname |
Confirm the provider’s exact hostname and port |
| Connection refused | Stopped service, wrong port, firewall, socket mismatch, or server outage | Have the host or server administrator check the service and network |
| Unknown database | Wrong DB_NAME, missing database, or incomplete migration |
Confirm the database exists and that the import completed |
| Successful independent connection but WordPress still fails | Wrong file being loaded, PHP-runtime difference, table-prefix mismatch, object-cache or proxy issue, or application error | Verify the active document root, configuration path, PHP logs, and WordPress environment |
Use a symptom-based decision tree
| Symptom | Most likely class | Next action |
|---|---|---|
| Failure began after editing configuration | Configuration or PHP syntax | Restore the known-good file and recheck all four constants |
| Failure began after a password reset | Authentication or missing grants | Update DB_PASSWORD and verify user assignment |
| Host status shows an outage | Provider or database service | Wait for recovery or open a support ticket |
Unknown database |
Wrong name or incomplete migration | Confirm the database and import |
Access denied |
User, password, or privileges | Reset credentials and reassign the user |
Unknown host |
Hostname, DNS, or network | Confirm host and port |
Connection refused |
Service, port, firewall, or socket | Escalate to the server administrator |
| Intermittent failures | Capacity, crashes, connection limits, or slow queries | Review resource graphs and MySQL/MariaDB logs |
| MySQL reports damaged tables | Database corruption | Back up, check, repair, or restore |
| Failure follows a plugin action | Resource, query, or application issue | Disable plugins and reactivate individually |
| Compromise indicators appear | Security incident | Isolate, preserve evidence, scan, and restore cleanly |
Check capacity and intermittent failures
If the site works sometimes, inspect database crashes, maximum-connections errors, disk exhaustion, slow or expensive queries, traffic spikes, object-cache or database-proxy failures, and host maintenance. A PHP memory increase does not create database capacity; PHP memory limits and database-server RAM or connection limits are separate resources.
Preserve relevant logs before restarting services if you administer the server. Review PHP, web-server, and MySQL/MariaDB logs, hosting resource graphs, container logs, and deployment activity. Repeatedly restarting a crashing service can erase useful evidence and does not address the underlying limit.
Repair damaged tables only after a backup
Repair is appropriate when a MySQL error identifies a damaged table, a host reports table problems, or a database check confirms corruption. It is not a remedy for an incorrect password, hostname, stopped service, DNS failure, or quota.
WP-CLI repair
wp db repairThis command invokes the MySQL repair utility using the credentials in wp-config.php: WP-CLI db repair. Run it only after confirming a usable backup and the intended WordPress path or multisite context.
phpMyAdmin or host tools
A provider can run checks and repairs through phpMyAdmin or server utilities. InnoDB corruption may not respond to a basic repair command, and a damaged database may require restoration from a known-good backup or specialist recovery. If you are unfamiliar with database administration, ask the host to perform the check after preserving a backup.
Why WordPress repair mode often does not help
As a temporary option, add this line to wp-config.php:
define( 'WP_ALLOW_REPAIR', true );Then visit:
https://example.com/wp-admin/maint/repair.phpWordPress must still reach the database far enough to load this page. Invalid credentials, an unavailable server, DNS failure, or a blocked connection can prevent it from opening. The endpoint does not require normal administrator authentication, so remove WP_ALLOW_REPAIR immediately after use. Prefer a host backup and WP-CLI or phpMyAdmin when those are available.
Rank #4
- Easily store and access 4TB of content on the go with the Seagate Portable Drive, a USB external hard drive.Specific uses: Personal
- Designed to work with Windows or Mac computers, this external hard drive makes backup a snap just drag and drop
- To get set up, connect the portable hard drive to a computer for automatic recognition no software required
- This USB drive provides plug and play simplicity with the included 18 inch USB 3.0 cable
- The available storage capacity may vary.
Isolate plugins and themes only when evidence points there
Plugins and themes do not normally cause invalid database credentials, but they can exhaust PHP or database connections, trigger expensive queries, break schema migrations, or affect only particular requests.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →If the dashboard is inaccessible, rename the filesystem directory wp-content/plugins to wp-content/plugins.hold. WordPress documents this filesystem method in its troubleshooting FAQ.
- Test the site with all plugins disabled.
- Rename the directory back to
plugins. - Reactivate plugins one at a time.
- Check PHP and database logs after each activation.
Switching temporarily to a default theme can exclude a theme-specific failure, although it is less likely to resolve a genuine connection or authentication error.
Migration, Docker, and local-development cases
After moving hosts
- Confirm the destination database was actually imported.
- Match the destination database name, user, password, host, and port to
wp-config.php. - Verify the user is assigned to the destination database.
- Confirm the separate database server permits the WordPress server to connect.
- Check that environment variables did not override the configuration file.
- Ensure the web server points to the migrated document root.
- Compare
$table_prefixwith the imported table names.
In Docker or another container setup
DB_HOST is often the database service name, such as db, rather than localhost. Inside the WordPress container, localhost means that same container, not the database container.
Check that both containers are running on the same network, the database health check passes, initialization has completed, persisted data is mounted, and the environment variables for database name, user, and password match the existing database. A WordPress container that starts before the database is ready may show the error temporarily.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
On local development machines
MAMP, XAMPP, Local, Docker, and similar stacks can use different ports, sockets, usernames, and passwords. WP-CLI may use a different PHP or database environment from the graphical local stack. Compare the command-line runtime with the environment serving the site; see the WP-CLI common issues guide.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Collect logs without exposing secrets
Use debugging to gather evidence, not to display internals to visitors. Temporarily set:
Best Value
- [Upgraded Version] - This external hard drive features a mirrored logo stripe combined with a striped anti-slip design, and the rounded corners of the casing make it easier to grip. The stripes also have a heat dissipation function, ensuring stable and fast data transfer.
- 【Ultra-thin and quiet】 - The motherboard adopts JMicron 578 noise-free solution, giving you a quiet working environment. Lightweight and portable size designed to fit in your pocket for easy portability.
- 【Ultra-Fast Data Transfers】 - Pairing this external hard drive with JMicron 578 solution USB 3.0 and USB 2.0 interfaces enables blazing-fast data transfer. It boasts theoretical read speeds of up to 125MB/s and write speeds of up to 103MB/s.
- 【Plug and Play】 - With no software to install, just plug it in and the drive is ready to use.The hard disk chip is wrapped with an aluminum anti-interference layer to increase heat dissipation and protect data.
- 【What You Get】 - 1 x Portable Hard Drive, 1 x USB 3.0 Cable, 1 x User Manual, Gift-type shell packaging ,Three-year manufacturer's warranty and free technical support services.
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );Inspect wp-content/debug.log, the PHP error log, web-server error log, MySQL/MariaDB error log, hosting resource graphs, and container or deployment logs. WP-CLI also documents the global --debug option and WordPress debugging settings in its troubleshooting guide.
Turn debugging off after diagnosis. Leaving WP_DEBUG_DISPLAY enabled on a production site can expose SQL errors, file paths, and other sensitive details.
Check for compromise when normal causes are ruled out
If the credentials are correct and the host confirms availability, inspect for unexpected changes to wp-config.php, unknown administrator accounts, modified plugins or themes, suspicious cron jobs, new PHP files in upload directories, malware warnings, and unexpected database users or grants.
Do not respond to a suspected compromise by restoring only wp-config.php or reinstalling WordPress files. Malicious database entries and backdoors can remain. Isolate the site, preserve logs, scan the files and database, rotate credentials from a clean device, and restore a known-clean backup or follow a specialist incident-response process. WordPress includes compromise among the possible causes in its common-errors guidance.
When to fix it yourself and when to escalate
Self-service is reasonable when
- You can access the files and hosting panel.
- The host is online and the database exists.
- The failure followed a known configuration change.
- You can create a verified database backup.
- The independent connection test identifies a simple credential or hostname mismatch.
Contact the host immediately when
- The database server is down or repeatedly crashing.
- The account has reached a storage, process, or connection limit.
- You cannot access database logs or restart a managed service.
- The database is remote or managed by another provider.
- InnoDB corruption or possible data loss is involved.
- The site is business-critical and no verified backup exists.
When escalating, include the timestamp, exact error, affected domain, whether failures are intermittent, the independent test result, and the changes made. Never include the database password.
Prevent another outage
- Keep automated database backups separate from file backups and periodically test a restoration.
- Record the database hostname, port, database name, and user in a secure password manager.
- Use staging for plugin, theme, PHP, and database upgrades.
- Monitor disk space, database health, connection limits, CPU, RAM, and slow queries.
- Document migration steps and verify the destination before changing DNS.
- Use least-privilege database users and rotate credentials through a documented procedure.
- Keep WordPress, PHP, plugins, and themes updated through a tested process.
- Set monitoring that checks both the front end and a database-dependent health endpoint.
Restoration checklist
- Confirm the host and database service are operational.
- Back up the database and download the current configuration.
- Verify
DB_NAME,DB_USER,DB_PASSWORD, andDB_HOST. - Confirm the user is assigned to the database and has the required grants.
- Run
wp db cli --debugor an equivalent independent client test. - Resolve the specific access, host, database, service, or capacity error shown.
- Repair or restore only when corruption is established and a backup exists.
- Disable plugins only when logs or timing suggest an application-level trigger.
- Turn off temporary debugging and repair settings.
- Retest the front end, administrator area, scheduled tasks, and key database-backed features.
Reinstalling WordPress is rarely the first answer: core files are usually not responsible for a database authentication or server-availability failure. A diagnostic sequence protects the database and gets you to the right administrator faster.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
