Identify the affected WordPress installation and the failing database connection before changing credentials, invoking repair or restoring data.
A WordPress database connection error tells you that the application has failed to establish the database connection it needs. It does not tell you to reinstall WordPress, delete tables or restore yesterday’s backup. First identify which installation is failing and what changed before the first failure.
Consider a fictional publisher migrating one website while several unrelated sites share the hosting account. The new site’s files open, but WordPress displays the database error. The immediate task is to check that site’s configured connection. Changing every database password in the account would create a second incident without explaining the first.
Record the symptom before choosing a repair
The official common-errors guide lists incorrect database name, username, password or host, and hosting-service problems such as downtime or an exhausted database quota. Treat these as possible causes. The text on the screen does not distinguish an incorrect setting from a temporarily unavailable service.
Record the public hostname, first known failure time, affected paths and the last successful administrator action. Distinguish a failure immediately after migration from an intermittent failure on a site whose configuration has not changed. Ask who changed hosting, deployment or database access, and preserve their timeline.
Use a short incident note rather than a collection of screenshots containing private account details. Include the error wording and the result you expected. If only one environment fails, name that environment clearly; staging and production should not become interchangeable labels during recovery.
Confirm the exact installation and database mapping
Before editing anything, have the authorized administrator establish a mapping between the domain, document root, WordPress configuration and intended database. In the fictional migration, the correct result is a single site’s files connected to its intended migrated data, with no changes to the neighboring installations.
Ask the host to confirm the database endpoint for that environment. Do not infer it from another website or copy a neighboring site’s configuration. A working administrator login elsewhere in the hosting account answers a different question from whether this application’s database connection works.
The wp-config.php reference documents the connection settings. Compare the intended database name, authorized user and host privately with the site’s effective configuration. Do not paste the configuration file or its password into a public forum, screenshot, support transcript or article.
| Observed situation | Evidence to request | Next decision |
|---|---|---|
| Failure began at migration cutover | Intended destination database and effective configuration | Correct an evidenced mapping or access mismatch |
| Previously working site now fails intermittently | Service health and resource evidence at matching times | Investigate availability rather than guessing a new password |
| Only the copied environment fails | Its own endpoint, user and deployment history | Keep the repair scoped to that environment |
| Administrator suspects damaged tables | Specific database diagnostics and a protected recovery copy | Plan repair or restoration only after diagnosis |
| Site returns after an unexplained restart | Incident timeline and service logs | Retain the unresolved cause instead of declaring a permanent fix |
Check service availability without creating more changes
Give the provider a narrow request: confirm whether the configured database service was available at the failure time, whether this site’s database had a quota restriction, and whether its authorized connection was rejected. Request a conclusion tied to evidence, not a generic recommendation to upgrade.
Record whether the application and database are in the intended environment. If a change is needed, identify its owner and rollback before applying it. Avoid repeatedly rotating a password while different people simultaneously edit the configuration; that makes it difficult to know which pair of settings is current.
For migrations, keep the old site’s recovery plan distinct from the new site’s fault diagnosis. The WordPress migration guide covers cutover responsibilities. A return to the previous environment needs an explicit content and write-handling decision, especially when readers have submitted new information.
Collect useful diagnostics privately
The WordPress debugging guide separates logging from displaying errors. WP_DEBUG_LOG depends on WP_DEBUG; WP_DEBUG_DISPLAY controls whether messages appear in page HTML. WordPress discourages using its debug tools on a live site by default. Prefer existing provider evidence and an isolated reproduction before introducing temporary diagnostics.
If an administrator approves temporary logging, agree where logs will be stored, who can read them and when the temporary settings will be removed. Check that the diagnostic output is not being presented to ordinary visitors. Review a short relevant interval instead of sharing an entire log containing unrelated requests.
Keep application observations and database-service observations separate. A browser shows the failed page; the provider may need other records to explain the connection. Absence of a useful application entry is not proof that the database is healthy.
Do not enable database repair as blind first aid
The configuration reference warns that enabling WP_ALLOW_REPAIR permits access to the repair functionality without logging in. It should be enabled only when needed and disabled afterward. A broken connection is not, by itself, evidence that running this facility is the appropriate operation.
If diagnostics identify damage, pause improvisation. Preserve a recoverable copy, establish the affected data and ask the responsible administrator for a repair or restore plan. The restorable WordPress backup guide explains why a backup listing is not the same as verified recovery.
Compare the recovery copy with the last successful writes. In the fictional publisher’s case, restoring a whole database could discard an article submitted after the backup. Document that decision instead of silently treating an older snapshot as the latest truth.
Agree on the observation period with the operator. An intermittent incident needs checks spanning its reported conditions, whereas a confirmed configuration mismatch needs a comparison against the corrected mapping. Keep that difference in the closure note.
Verify the narrow fix and remove temporary exposure
- Confirm the intended installation now connects to the intended database.
- Open an affected public page and the authorized administration route.
- Check that the expected recent content is present.
- Review the incident’s failing operation in a controlled way.
- Disable temporary repair or diagnostic settings and protect retained evidence.
- Confirm unrelated installations were outside the change.
If a different WordPress fault remains after the connection is restored, diagnose it separately. The plugin-conflict guide provides a controlled isolation workflow. Close this incident with the observed cause, exact repair and remaining uncertainty, rather than merely noting that the homepage loaded once.
Sources and verification
Editorial review 2026-10-15. Source check dates are recorded separately. Notes describe what each source supports and its limits.
View sources
- WordPress: common errors, database connection sectionChecked Incorrect database settings, service outages and quota problems are possible causes.
Limits: The error message alone does not establish which cause applies. - WordPress Common APIs: wp-config.phpChecked Database configuration and the unauthenticated access enabled by WP_ALLOW_REPAIR.
Limits: A configuration reference is not evidence that a particular database is corrupt. - WordPress: debuggingChecked Debug logging, separate display control and the need to avoid live debugging by default.
Limits: Application logs may not contain the underlying database-service evidence.