{"id":9808,"date":"2026-06-07T16:36:29","date_gmt":"2026-06-07T14:36:29","guid":{"rendered":"https:\/\/mybox.com\/help\/?post_type=manual_kb&#038;p=9808"},"modified":"2026-06-07T16:36:30","modified_gmt":"2026-06-07T14:36:30","slug":"how-to-set-a-custom-database-connection-error-page-in-wordpress","status":"publish","type":"manual_kb","link":"https:\/\/mybox.com\/help\/en\/knowledgebase\/how-to-set-a-custom-database-connection-error-page-in-wordpress\/","title":{"rendered":"How to Set a Custom Database Connection Error Page in WordPress"},"content":{"rendered":"\n<div class=\"translation-block translation-block-merged\">\n<p class=\"wp-block-paragraph\">By default, when WordPress cannot establish a connection to the database, visitors see a generic error message similar to:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>Error establishing a database connection\n<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">You can replace this default message with a custom error page that provides more useful information to visitors and better matches your website&#8217;s branding.<\/p>\n\n\n\n<\/div>\n\n<div id=\"mybox-170230368\" class=\"mybox-content mybox-entity-placement\"><div class=\"early-access-banner-inpost\">\r\n  <div class=\"banner-left-inpost\">\r\n    <div class=\"icon-box-inpost\">\r\n      <img decoding=\"async\" src=\"https:\/\/mybox.com\/help\/wp-content\/uploads\/2026\/02\/square-info-icon.svg\" alt=\"Info\">\r\n    <\/div>\r\n    <div class=\"text-box-inpost\">\r\n      <span class=\"label-inpost\"><span class=\"translation-block translation-block-banner-text\">Early access<\/span><\/span>\r\n      <h4><span class=\"translation-block translation-block-banner-text\">Still need help?<\/span><\/h4>\r\n      <p><span class=\"translation-block translation-block-banner-text\">Contact our customer service team.<\/span><\/p>\r\n    <\/div>\r\n  <\/div>\r\n\r\n  <div class=\"banner-right-inpost\">\r\n    <a href=\"https:\/\/panel.mybox.com\/helpdesk2\/v\/list\/\" class=\"banner-button-inpost\"><span class=\"translation-block translation-block-banner-text\">Message us<\/span><\/a>\r\n  <\/div>\r\n<\/div><\/div>\n\n<div class=\"translation-block translation-block-merged\"><p class=\"wp-block-paragraph\">WordPress allows this by using a custom file named:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>db-error.php\n<\/code><\/pre>\n\n\n\n<div id=\"ez-toc-container\" class=\"ez-toc-v2_0_86 ez-toc-wrap-left counter-hierarchy ez-toc-counter ez-toc-custom ez-toc-container-direction\">\n<div class=\"ez-toc-title-container\">\n<p class=\"ez-toc-title\" style=\"cursor:inherit\">Table of Contents<\/p>\n<span class=\"ez-toc-title-toggle\"><\/span><\/div>\n<nav><ul class='ez-toc-list ez-toc-list-level-1 ' ><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-1\" href=\"https:\/\/mybox.com\/help\/en\/knowledgebase\/how-to-set-a-custom-database-connection-error-page-in-wordpress\/#How_It_Works\" >How It Works<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-2\" href=\"https:\/\/mybox.com\/help\/en\/knowledgebase\/how-to-set-a-custom-database-connection-error-page-in-wordpress\/#Step_1_Create_the_File\" >Step 1: Create the File<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-3\" href=\"https:\/\/mybox.com\/help\/en\/knowledgebase\/how-to-set-a-custom-database-connection-error-page-in-wordpress\/#Step_2_Add_the_Error_Page_Content\" >Step 2: Add the Error Page Content<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-4\" href=\"https:\/\/mybox.com\/help\/en\/knowledgebase\/how-to-set-a-custom-database-connection-error-page-in-wordpress\/#Step_3_Upload_the_File\" >Step 3: Upload the File<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-5\" href=\"https:\/\/mybox.com\/help\/en\/knowledgebase\/how-to-set-a-custom-database-connection-error-page-in-wordpress\/#Understanding_the_HTTP_Headers\" >Understanding the HTTP Headers<\/a><ul class='ez-toc-list-level-3' ><li class='ez-toc-heading-level-3'><a class=\"ez-toc-link ez-toc-heading-6\" href=\"https:\/\/mybox.com\/help\/en\/knowledgebase\/how-to-set-a-custom-database-connection-error-page-in-wordpress\/#503_Service_Temporarily_Unavailable\" >503 Service Temporarily Unavailable<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-3'><a class=\"ez-toc-link ez-toc-heading-7\" href=\"https:\/\/mybox.com\/help\/en\/knowledgebase\/how-to-set-a-custom-database-connection-error-page-in-wordpress\/#Retry-After\" >Retry-After<\/a><\/li><\/ul><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-8\" href=\"https:\/\/mybox.com\/help\/en\/knowledgebase\/how-to-set-a-custom-database-connection-error-page-in-wordpress\/#Customizing_the_Error_Page\" >Customizing the Error Page<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-9\" href=\"https:\/\/mybox.com\/help\/en\/knowledgebase\/how-to-set-a-custom-database-connection-error-page-in-wordpress\/#When_Is_This_Useful\" >When Is This Useful?<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-10\" href=\"https:\/\/mybox.com\/help\/en\/knowledgebase\/how-to-set-a-custom-database-connection-error-page-in-wordpress\/#Testing_the_Configuration\" >Testing the Configuration<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-11\" href=\"https:\/\/mybox.com\/help\/en\/knowledgebase\/how-to-set-a-custom-database-connection-error-page-in-wordpress\/#Summary\" >Summary<\/a><\/li><\/ul><\/nav><\/div>\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"How_It_Works\"><\/span>How It Works<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Whenever WordPress encounters a database connection problem, it checks whether a custom error file exists in the following location:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>wp-content\/db-error.php\n<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">If the file exists, WordPress displays its contents instead of the standard error message.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Step_1_Create_the_File\"><\/span>Step 1: Create the File<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Create a file named:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>db-error.php\n<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">using any text editor.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Step_2_Add_the_Error_Page_Content\"><\/span>Step 2: Add the Error Page Content<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">You can use the following example:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>&lt;?php\n\/\/ Custom database connection error page\n\nheader('HTTP\/1.1 503 Service Temporarily Unavailable');\nheader('Status: 503 Service Temporarily Unavailable');\nheader('Retry-After: 600');\n\n?&gt;\n\n&lt;!DOCTYPE html&gt;\n&lt;html&gt;\n&lt;head&gt;\n    &lt;meta charset=\"utf-8\"&gt;\n    &lt;title&gt;Temporary Service Interruption&lt;\/title&gt;\n\n    &lt;style&gt;\n        body {\n            background: #c0392b;\n            color: #ffffff;\n            font-family: Arial, sans-serif;\n            text-align: center;\n            padding: 80px 20px;\n        }\n\n        h1 {\n            font-size: 42px;\n        }\n\n        p {\n            font-size: 20px;\n        }\n    &lt;\/style&gt;\n&lt;\/head&gt;\n&lt;body&gt;\n\n    &lt;h1&gt;We'll Be Back Shortly&lt;\/h1&gt;\n\n    &lt;p&gt;\n        We are currently experiencing a temporary database connection issue.\n    &lt;\/p&gt;\n\n    &lt;p&gt;\n        Please try again in a few minutes.\n    &lt;\/p&gt;\n\n&lt;\/body&gt;\n&lt;\/html&gt;\n<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Step_3_Upload_the_File\"><\/span>Step 3: Upload the File<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Connect to your hosting account using FTP, SFTP, or your preferred file manager.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Navigate to your WordPress installation directory.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">By default, the file should be uploaded to:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>public_html\/wp-content\n<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">The final path should be:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>public_html\/wp-content\/db-error.php\n<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Understanding_the_HTTP_Headers\"><\/span>Understanding the HTTP Headers<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">The example includes the following headers:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>header('HTTP\/1.1 503 Service Temporarily Unavailable');\nheader('Retry-After: 600');\n<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"503_Service_Temporarily_Unavailable\"><\/span>503 Service Temporarily Unavailable<span class=\"ez-toc-section-end\"><\/span><\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Informs search engines and visitors that the issue is temporary rather than permanent.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Retry-After\"><\/span>Retry-After<span class=\"ez-toc-section-end\"><\/span><\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Tells browsers and search engines when they should try accessing the website again.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">In this example:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>600 seconds = 10 minutes\n<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Customizing_the_Error_Page\"><\/span>Customizing the Error Page<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">You can modify the page to include:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Your company logo.<\/li>\n\n\n\n<li>Contact information.<\/li>\n\n\n\n<li>Maintenance notices.<\/li>\n\n\n\n<li>Estimated recovery times.<\/li>\n\n\n\n<li>Custom branding and styling.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">For example:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>&lt;img src=\"\/logo.png\" alt=\"Company Logo\"&gt;\n<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">or<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>&lt;p&gt;Our team is already working on resolving the issue.&lt;\/p&gt;\n<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"When_Is_This_Useful\"><\/span>When Is This Useful?<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">A custom database error page can be helpful when:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Performing database maintenance.<\/li>\n\n\n\n<li>Troubleshooting database issues.<\/li>\n\n\n\n<li>Migrating websites.<\/li>\n\n\n\n<li>Experiencing temporary database outages.<\/li>\n\n\n\n<li>Improving the user experience during unexpected downtime.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Testing_the_Configuration\"><\/span>Testing the Configuration<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">After uploading the file, WordPress will automatically use it whenever a database connection error occurs.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">You generally do not need to modify any WordPress settings for this feature to work.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Summary\"><\/span>Summary<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">To create a custom database connection error page in WordPress:<\/p>\n\n\n\n<ol class=\"wp-block-list\">\n<li>Create a file named:<\/li>\n<\/ol>\n\n\n\n<pre class=\"wp-block-code\"><code>db-error.php\n<\/code><\/pre>\n\n\n\n<ol start=\"2\" class=\"wp-block-list\">\n<li>Add your custom PHP and HTML content.<\/li>\n\n\n\n<li>Upload the file to:<\/li>\n<\/ol>\n\n\n\n<pre class=\"wp-block-code\"><code>wp-content\n<\/code><\/pre>\n\n\n\n<ol start=\"4\" class=\"wp-block-list\">\n<li>WordPress will automatically display your custom page whenever a database connection issue occurs.<\/li>\n<\/ol>\n\n\n\n<p class=\"wp-block-paragraph\">This allows you to present a professional message to visitors instead of the default WordPress database error screen.<\/p>\n<\/div>\n","protected":false},"author":1,"featured_media":0,"parent":0,"menu_order":0,"template":"","format":"standard","manualknowledgebasecat":[58],"manual_kb_tag":[643,2886,4800,4801,4802,4803,4804,190,406,636],"class_list":["post-9808","manual_kb","type-manual_kb","status-publish","format-standard","hentry","manualknowledgebasecat-web-applications-cms","manual_kb_tag-public-html-directory","manual_kb_tag-wordpress-content-directory","manual_kb_tag-custom-error-page","manual_kb_tag-database-error-page","manual_kb_tag-50-service-temporarily-unavailable","manual_kb_tag-retry-after-header","manual_kb_tag-database-maintenance","manual_kb_tag-wordpress","manual_kb_tag-website-downtime","manual_kb_tag-database-connection-error"],"_links":{"self":[{"href":"https:\/\/mybox.com\/help\/en\/wp-json\/wp\/v2\/manual_kb\/9808","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/mybox.com\/help\/en\/wp-json\/wp\/v2\/manual_kb"}],"about":[{"href":"https:\/\/mybox.com\/help\/en\/wp-json\/wp\/v2\/types\/manual_kb"}],"author":[{"embeddable":true,"href":"https:\/\/mybox.com\/help\/en\/wp-json\/wp\/v2\/users\/1"}],"version-history":[{"count":1,"href":"https:\/\/mybox.com\/help\/en\/wp-json\/wp\/v2\/manual_kb\/9808\/revisions"}],"predecessor-version":[{"id":9809,"href":"https:\/\/mybox.com\/help\/en\/wp-json\/wp\/v2\/manual_kb\/9808\/revisions\/9809"}],"wp:attachment":[{"href":"https:\/\/mybox.com\/help\/en\/wp-json\/wp\/v2\/media?parent=9808"}],"wp:term":[{"taxonomy":"manualknowledgebasecat","embeddable":true,"href":"https:\/\/mybox.com\/help\/en\/wp-json\/wp\/v2\/manualknowledgebasecat?post=9808"},{"taxonomy":"manual_kb_tag","embeddable":true,"href":"https:\/\/mybox.com\/help\/en\/wp-json\/wp\/v2\/manual_kb_tag?post=9808"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}