Create a standalone PHP file named db-error.php in WordPress’s active content directory—normally wp-content/db-error.php. WordPress loads this file when it cannot use the database, instead of showing its standard database-error screen. Set the response status to HTTP 500 and keep the file independent of WordPress, themes, plugins, and database queries.
What this file does—and what it cannot do
db-error.php changes the page visitors see during a database failure. It does not reconnect WordPress, repair credentials, restart a database server, or increase a hosting quota. Treat it as a controlled maintenance response while you investigate the underlying outage.
WordPress’s dead_db() path uses the custom template when it exists in the active content directory. If the file is absent, WordPress uses its normal database-error display. The default response is HTTP 500, and WordPress’s developer reference says custom database messages should do the same.
Before you create the file
- Have filesystem or deployment access to the WordPress installation. You can use your host’s file manager, SFTP, SSH, or your normal deployment pipeline.
- Identify the active content directory. It is usually
wp-content, but a site can configure another location. WordPress’s documented path isWP_CONTENT_DIR . '/db-error.php'. - Prepare a support or status URL only if it works independently of WordPress and the affected database.
How to add db-error.php
- Open the active content directory. For a conventional installation, open the directory containing
plugins,themes, anduploads:wp-content. - Create the file at its exact path. Save it as
wp-content/db-error.php. The name is case-sensitive on many servers; do not add a second extension such as.php.txt. - Use a standalone response. Do not call WordPress bootstrap files, load a theme, invoke plugins, query
$wpdb, or depend on WordPress functions. Those dependencies may be unavailable precisely when this file is being served. - Send status 500 before the body. Set the status before output starts, then send a content type and render simple HTML.
- Deploy and inspect the result. Review the file through the same filesystem or deployment process used for the site. A real database failure is needed to exercise this path; do not take a production site offline merely to test it.
Minimal standalone example
<?php
http_response_code( 500 );
header( 'Content-Type: text/html; charset=utf-8' );
?>
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Temporarily unavailable</title>
</head>
<body>
<main>
<h1>We’ll be back shortly</h1>
<p>This site is temporarily unable to connect to its database. Please try again later.</p>
</main>
</body>
</html>This is an illustrative implementation. The important WordPress compatibility requirement is preserving the 500 status; the visual design, wording, and CSS are yours to choose. Inline CSS is generally safer than loading assets through WordPress, but the developer reference does not require a particular styling or asset-loading method.
Recommended Free Tools
Why HTTP 500 matters
HTTP 500 tells browsers, crawlers, and monitoring systems that the server failed to complete the request. WordPress documents the status partly to discourage search engines from caching the temporary database-error message. A friendly-looking page that returns 200 can be mistaken for a successful, indexable page, so do not omit or replace the 500 response.
Choose a useful message
- State that the site is temporarily unable to reach its database.
- Ask visitors to try again later rather than suggesting that they change browser settings.
- Provide a status page, email address, or phone number only when that channel remains available without this WordPress installation.
- Do not expose database hostnames, usernames, passwords, SQL errors, file paths, or stack traces.
db-error.php versus db.php
| File | Purpose | Use for a visitor-facing database error page? |
|---|---|---|
wp-content/db-error.php |
Replaces the default display when WordPress enters its database-error path. | Yes |
wp-content/db.php |
A database drop-in that can replace or extend the global $wpdb database object. |
No; it is a database-layer customization. |
Do not edit core files such as wp-includes/functions.php to change this message. The content-directory template is the documented customization point.
Rank #2
How to troubleshoot the underlying database failure
If visitors are seeing the custom page, investigate the connection separately. WordPress troubleshooting guidance identifies four values in wp-config.php that should be checked:
- Database name
- Database username
- Database password
- Database host
Check for recent migrations, restored backups, changed passwords, or hostnames that differ between environments. If all four values are correct, ask the hosting provider whether the database server is down, the account has reached a database quota, or another host-side restriction is preventing connections.
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 errorsRank #3
PHP error-display settings are not a substitute for this work. WordPress documents database errors as being handled by wpdb, independently of PHP error-reporting settings. Changing display_errors may alter other PHP output but will not fix a failed database connection or install the custom template.
Why Recovery Mode is not the solution
WordPress Recovery Mode is designed for some fatal PHP errors during regular page loads, commonly involving a plugin, theme, or custom code. Its documentation does not make it a database-connection error-page mechanism, and it does not replace db-error.php. Use the custom template for the visitor response and normal database diagnostics for the outage.
Quick Recap
Deployment and security checklist
- Path: the file is in the active content directory, not the web root, theme directory, or
wp-includes. - Name: exactly
db-error.php. - Dependencies: no WordPress, theme, plugin, or database calls.
- Status: HTTP 500 is sent before page output.
- Output: valid HTML with a clear, non-sensitive message.
- Recovery: remove or update the file if your deployment process treats it as a temporary override, and confirm the database credentials and host condition are repaired.
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.
