{"id":2759,"date":"2007-12-30T15:08:18","date_gmt":"2007-12-30T09:38:18","guid":{"rendered":"https:\/\/www.quickonlinetips.com\/archives\/2007\/12\/create-custom-wordpress-database-error-pages\/"},"modified":"2026-10-12T19:05:49","modified_gmt":"2026-10-12T13:35:49","slug":"create-custom-wordpress-database-error-pages","status":"publish","type":"post","link":"https:\/\/www.quickonlinetips.com\/archives\/2007\/12\/create-custom-wordpress-database-error-pages\/","title":{"rendered":"Error Establishing a Database Connection in WordPress: Fixes and a Custom Error Page"},"content":{"rendered":"<p>Back in 2007, while upgrading WordPress, I learned a neat trick: put a file called db-error.php in wp-content, and WordPress shows your own friendly message instead of a bare database error. It still works in 2026. But first, here&#8217;s how to fix the dreaded <strong>error establishing a database connection<\/strong> message itself.<\/p>\n<p><img decoding=\"async\" class=\"aligncenter size-large wp-image-64769\" src=\"https:\/\/www.quickonlinetips.com\/archives\/wp-content\/uploads\/error-establishing-database-connection-1024x538.webp\" alt=\"Error establishing a database connection in WordPress\" width=\"1024\" height=\"538\" srcset=\"https:\/\/www.quickonlinetips.com\/archives\/wp-content\/uploads\/error-establishing-database-connection-1024x538.webp 1024w, https:\/\/www.quickonlinetips.com\/archives\/wp-content\/uploads\/error-establishing-database-connection-300x158.webp 300w, https:\/\/www.quickonlinetips.com\/archives\/wp-content\/uploads\/error-establishing-database-connection-150x79.webp 150w, https:\/\/www.quickonlinetips.com\/archives\/wp-content\/uploads\/error-establishing-database-connection-768x403.webp 768w, https:\/\/www.quickonlinetips.com\/archives\/wp-content\/uploads\/error-establishing-database-connection.webp 1200w\" sizes=\"(max-width: 1024px) 100vw, 1024px\" \/><\/p>\n<p><strong>Quick answer:<\/strong> This error means WordPress can&#8217;t talk to its MySQL or MariaDB database. Check that DB_NAME, DB_USER, DB_PASSWORD and DB_HOST in wp-config.php match your hosting database details, make sure the database server is running (ask your host), and repair corrupted tables with WP_ALLOW_REPAIR. Add a custom wp-content\/db-error.php so visitors see a helpful message during outages.<\/p>\n<div id=\"ez-toc-container\" class=\"ez-toc-v2_0_89 counter-hierarchy ez-toc-counter ez-toc-custom ez-toc-container-direction\">\n<p class=\"ez-toc-title\" style=\"cursor:inherit\">Table of Contents<\/p>\n<label for=\"ez-toc-cssicon-toggle-item-6ae1cc27b2930\" class=\"ez-toc-cssicon-toggle-label\"><span class=\"ez-toc-cssicon\"><span class=\"eztoc-hide\" style=\"display:none;\">Toggle<\/span><span class=\"ez-toc-icon-toggle-span\"><svg style=\"fill: #1a202c;color:#1a202c\" xmlns=\"http:\/\/www.w3.org\/2000\/svg\" class=\"list-377408\" width=\"20px\" height=\"20px\" viewBox=\"0 0 24 24\" fill=\"none\"><path d=\"M6 6H4v2h2V6zm14 0H8v2h12V6zM4 11h2v2H4v-2zm16 0H8v2h12v-2zM4 16h2v2H4v-2zm16 0H8v2h12v-2z\" fill=\"currentColor\"><\/path><\/svg><svg style=\"fill: #1a202c;color:#1a202c\" class=\"arrow-unsorted-368013\" xmlns=\"http:\/\/www.w3.org\/2000\/svg\" width=\"10px\" height=\"10px\" viewBox=\"0 0 24 24\" version=\"1.2\" baseProfile=\"tiny\"><path d=\"M18.2 9.3l-6.2-6.3-6.2 6.3c-.2.2-.3.4-.3.7s.1.5.3.7c.2.2.4.3.7.3h11c.3 0 .5-.1.7-.3.2-.2.3-.5.3-.7s-.1-.5-.3-.7zM5.8 14.7l6.2 6.3 6.2-6.3c.2-.2.3-.5.3-.7s-.1-.5-.3-.7c-.2-.2-.4-.3-.7-.3h-11c-.3 0-.5.1-.7.3-.2.2-.3.5-.3.7s.1.5.3.7z\"\/><\/svg><\/span><\/span><\/label><input type=\"checkbox\"  id=\"ez-toc-cssicon-toggle-item-6ae1cc27b2930\" checked aria-label=\"Toggle\" \/><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:\/\/www.quickonlinetips.com\/archives\/2007\/12\/create-custom-wordpress-database-error-pages\/#How_to_fix_error_establishing_a_database_connection\" >How to fix error establishing a database connection<\/a><ul class='ez-toc-list-level-3' ><li class='ez-toc-heading-level-3'><a class=\"ez-toc-link ez-toc-heading-2\" href=\"https:\/\/www.quickonlinetips.com\/archives\/2007\/12\/create-custom-wordpress-database-error-pages\/#1_Check_wp-configphp_credentials\" >1. Check wp-config.php credentials<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-3'><a class=\"ez-toc-link ez-toc-heading-3\" href=\"https:\/\/www.quickonlinetips.com\/archives\/2007\/12\/create-custom-wordpress-database-error-pages\/#2_Check_the_database_server\" >2. Check the database server<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-3'><a class=\"ez-toc-link ez-toc-heading-4\" href=\"https:\/\/www.quickonlinetips.com\/archives\/2007\/12\/create-custom-wordpress-database-error-pages\/#3_Repair_the_database\" >3. Repair the database<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-3'><a class=\"ez-toc-link ez-toc-heading-5\" href=\"https:\/\/www.quickonlinetips.com\/archives\/2007\/12\/create-custom-wordpress-database-error-pages\/#4_Reset_the_database_user_password\" >4. Reset the database user password<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-3'><a class=\"ez-toc-link ez-toc-heading-6\" href=\"https:\/\/www.quickonlinetips.com\/archives\/2007\/12\/create-custom-wordpress-database-error-pages\/#5_Restore_from_backup\" >5. Restore from backup<\/a><\/li><\/ul><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-7\" href=\"https:\/\/www.quickonlinetips.com\/archives\/2007\/12\/create-custom-wordpress-database-error-pages\/#Create_a_custom_db-errorphp_page\" >Create a custom db-error.php page<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-8\" href=\"https:\/\/www.quickonlinetips.com\/archives\/2007\/12\/create-custom-wordpress-database-error-pages\/#Prevent_it_happening_again\" >Prevent it happening again<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-9\" href=\"https:\/\/www.quickonlinetips.com\/archives\/2007\/12\/create-custom-wordpress-database-error-pages\/#FAQ\" >FAQ<\/a><ul class='ez-toc-list-level-3' ><li class='ez-toc-heading-level-3'><a class=\"ez-toc-link ez-toc-heading-10\" href=\"https:\/\/www.quickonlinetips.com\/archives\/2007\/12\/create-custom-wordpress-database-error-pages\/#Why_does_the_error_appear_only_sometimes\" >Why does the error appear only sometimes?<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-3'><a class=\"ez-toc-link ez-toc-heading-11\" href=\"https:\/\/www.quickonlinetips.com\/archives\/2007\/12\/create-custom-wordpress-database-error-pages\/#Can_a_plugin_cause_this_error\" >Can a plugin cause this error?<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-3'><a class=\"ez-toc-link ez-toc-heading-12\" href=\"https:\/\/www.quickonlinetips.com\/archives\/2007\/12\/create-custom-wordpress-database-error-pages\/#Does_db-errorphp_survive_WordPress_updates\" >Does db-error.php survive WordPress updates?<\/a><\/li><\/ul><\/li><\/ul><\/nav><\/div>\n<h2><span class=\"ez-toc-section\" id=\"How_to_fix_error_establishing_a_database_connection\"><\/span>How to fix error establishing a database connection<span class=\"ez-toc-section-end\"><\/span><\/h2>\n<h3><span class=\"ez-toc-section\" id=\"1_Check_wp-configphp_credentials\"><\/span>1. Check wp-config.php credentials<span class=\"ez-toc-section-end\"><\/span><\/h3>\n<p>Open wp-config.php in your host&#8217;s file manager and compare DB_NAME, DB_USER, DB_PASSWORD and DB_HOST with the database details in your hosting panel. DB_HOST is often <code>localhost<\/code> but some hosts use a hostname or port.<\/p>\n<h3><span class=\"ez-toc-section\" id=\"2_Check_the_database_server\"><\/span>2. Check the database server<span class=\"ez-toc-section-end\"><\/span><\/h3>\n<p>If the credentials are correct, the database server may be down or overloaded. Check your host&#8217;s status page or contact support. On shared hosting, traffic spikes can hit connection limits.<\/p>\n<h3><span class=\"ez-toc-section\" id=\"3_Repair_the_database\"><\/span>3. Repair the database<span class=\"ez-toc-section-end\"><\/span><\/h3>\n<ol>\n<li>Add <code>define('WP_ALLOW_REPAIR', true);<\/code> to wp-config.php.<\/li>\n<li>Visit yoursite.com\/wp-admin\/maint\/repair.php and click Repair Database.<\/li>\n<li>Remove the line afterwards; the page doesn&#8217;t require login.<\/li>\n<\/ol>\n<h3><span class=\"ez-toc-section\" id=\"4_Reset_the_database_user_password\"><\/span>4. Reset the database user password<span class=\"ez-toc-section-end\"><\/span><\/h3>\n<p>In your hosting panel, reset the MySQL user&#8217;s password and update wp-config.php to match.<\/p>\n<h3><span class=\"ez-toc-section\" id=\"5_Restore_from_backup\"><\/span>5. Restore from backup<span class=\"ez-toc-section-end\"><\/span><\/h3>\n<p>If tables are badly damaged, restore a recent backup. See how to <a href=\"https:\/\/www.quickonlinetips.com\/archives\/2009\/10\/backup-restore-wordpress-database\/\">back up and restore a WordPress database<\/a>.<\/p>\n<h2><span class=\"ez-toc-section\" id=\"Create_a_custom_db-errorphp_page\"><\/span>Create a custom db-error.php page<span class=\"ez-toc-section-end\"><\/span><\/h2>\n<p>Create a file named <code>db-error.php<\/code> in wp-content with simple HTML (it can&#8217;t use WordPress functions because the database is down):<\/p>\n<pre><code>&lt;?php header('HTTP\/1.1 503 Service Temporarily Unavailable'); header('Retry-After: 600'); ?&gt;\n&lt;!doctype html&gt;\n&lt;html&gt;&lt;head&gt;&lt;title&gt;Back soon&lt;\/title&gt;&lt;\/head&gt;\n&lt;body&gt;&lt;h1&gt;We'll be right back&lt;\/h1&gt;\n&lt;p&gt;The site is having a temporary database problem. Please check again in a few minutes.&lt;\/p&gt;&lt;\/body&gt;&lt;\/html&gt;<\/code><\/pre>\n<p>The 503 status tells search engines the outage is temporary, which protects your rankings.<\/p>\n<h2><span class=\"ez-toc-section\" id=\"Prevent_it_happening_again\"><\/span>Prevent it happening again<span class=\"ez-toc-section-end\"><\/span><\/h2>\n<ul>\n<li>Keep regular off-site backups.<\/li>\n<li>Use caching to reduce database load.<\/li>\n<li><a href=\"https:\/\/www.quickonlinetips.com\/archives\/2011\/06\/optimize-wordpress-database\/\">Optimize your WordPress database<\/a> occasionally.<\/li>\n<li>Upgrade hosting if you often hit connection limits.<\/li>\n<\/ul>\n<h2><span class=\"ez-toc-section\" id=\"FAQ\"><\/span>FAQ<span class=\"ez-toc-section-end\"><\/span><\/h2>\n<h3><span class=\"ez-toc-section\" id=\"Why_does_the_error_appear_only_sometimes\"><\/span>Why does the error appear only sometimes?<span class=\"ez-toc-section-end\"><\/span><\/h3>\n<p>Usually the database server is overloaded or hitting connection limits during traffic spikes.<\/p>\n<h3><span class=\"ez-toc-section\" id=\"Can_a_plugin_cause_this_error\"><\/span>Can a plugin cause this error?<span class=\"ez-toc-section-end\"><\/span><\/h3>\n<p>Rarely; it&#8217;s usually credentials, a server problem or corrupted tables.<\/p>\n<h3><span class=\"ez-toc-section\" id=\"Does_db-errorphp_survive_WordPress_updates\"><\/span>Does db-error.php survive WordPress updates?<span class=\"ez-toc-section-end\"><\/span><\/h3>\n<p>Yes, updates don&#8217;t touch files you add to wp-content.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Back in 2007, while upgrading WordPress, I learned a neat trick: put a file called db-error.php in wp-content, and WordPress&#8230;<\/p>\n","protected":false},"author":4,"featured_media":64769,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_kad_post_transparent":"","_kad_post_title":"","_kad_post_layout":"","_kad_post_sidebar_id":"","_kad_post_content_style":"","_kad_post_vertical_padding":"","_kad_post_feature":"","_kad_post_feature_position":"","_kad_post_header":false,"_kad_post_footer":false,"_kad_post_classname":"","footnotes":""},"categories":[6,25],"tags":[17],"class_list":["post-2759","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-blogging","category-domain-hosting","tag-wordpress"],"_links":{"self":[{"href":"https:\/\/www.quickonlinetips.com\/archives\/wp-json\/wp\/v2\/posts\/2759","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.quickonlinetips.com\/archives\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.quickonlinetips.com\/archives\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.quickonlinetips.com\/archives\/wp-json\/wp\/v2\/users\/4"}],"replies":[{"embeddable":true,"href":"https:\/\/www.quickonlinetips.com\/archives\/wp-json\/wp\/v2\/comments?post=2759"}],"version-history":[{"count":1,"href":"https:\/\/www.quickonlinetips.com\/archives\/wp-json\/wp\/v2\/posts\/2759\/revisions"}],"predecessor-version":[{"id":64770,"href":"https:\/\/www.quickonlinetips.com\/archives\/wp-json\/wp\/v2\/posts\/2759\/revisions\/64770"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.quickonlinetips.com\/archives\/wp-json\/wp\/v2\/media\/64769"}],"wp:attachment":[{"href":"https:\/\/www.quickonlinetips.com\/archives\/wp-json\/wp\/v2\/media?parent=2759"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.quickonlinetips.com\/archives\/wp-json\/wp\/v2\/categories?post=2759"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.quickonlinetips.com\/archives\/wp-json\/wp\/v2\/tags?post=2759"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}