How to Set a Custom Database Connection Error Page in WordPress

By default, when WordPress cannot establish a connection to the database, visitors see a generic error message similar to:

Error establishing a database connection

You can replace this default message with a custom error page that provides more useful information to visitors and better matches your website’s branding.

WordPress allows this by using a custom file named:

db-error.php

How It Works

Whenever WordPress encounters a database connection problem, it checks whether a custom error file exists in the following location:

wp-content/db-error.php

If the file exists, WordPress displays its contents instead of the standard error message.

Step 1: Create the File

Create a file named:

db-error.php

using any text editor.

Step 2: Add the Error Page Content

You can use the following example:

<?php
// Custom database connection error page

header('HTTP/1.1 503 Service Temporarily Unavailable');
header('Status: 503 Service Temporarily Unavailable');
header('Retry-After: 600');

?>

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Temporary Service Interruption</title>

    <style>
        body {
            background: #c0392b;
            color: #ffffff;
            font-family: Arial, sans-serif;
            text-align: center;
            padding: 80px 20px;
        }

        h1 {
            font-size: 42px;
        }

        p {
            font-size: 20px;
        }
    </style>
</head>
<body>

    <h1>We'll Be Back Shortly</h1>

    <p>
        We are currently experiencing a temporary database connection issue.
    </p>

    <p>
        Please try again in a few minutes.
    </p>

</body>
</html>

Step 3: Upload the File

Connect to your hosting account using FTP, SFTP, or your preferred file manager.

Navigate to your WordPress installation directory.

By default, the file should be uploaded to:

public_html/wp-content

The final path should be:

public_html/wp-content/db-error.php

Understanding the HTTP Headers

The example includes the following headers:

header('HTTP/1.1 503 Service Temporarily Unavailable');
header('Retry-After: 600');

503 Service Temporarily Unavailable

Informs search engines and visitors that the issue is temporary rather than permanent.

Retry-After

Tells browsers and search engines when they should try accessing the website again.

In this example:

600 seconds = 10 minutes

Customizing the Error Page

You can modify the page to include:

• Your company logo.
• Contact information.
• Maintenance notices.
• Estimated recovery times.
• Custom branding and styling.

For example:

<img src="/logo.png" alt="Company Logo">

or

<p>Our team is already working on resolving the issue.</p>

When Is This Useful?

A custom database error page can be helpful when:

• Performing database maintenance.
• Troubleshooting database issues.
• Migrating websites.
• Experiencing temporary database outages.
• Improving the user experience during unexpected downtime.

Testing the Configuration

After uploading the file, WordPress will automatically use it whenever a database connection error occurs.

You generally do not need to modify any WordPress settings for this feature to work.

Summary

To create a custom database connection error page in WordPress:

1. Create a file named:

db-error.php

2. Add your custom PHP and HTML content.
3. Upload the file to:

wp-content

4. WordPress will automatically display your custom page whenever a database connection issue occurs.

This allows you to present a professional message to visitors instead of the default WordPress database error screen.