Creating a custom WordPress database error page

a better looking databse error in wordpress

This is a quick tutorial on how to have WordPress show a custom error page when there’s a database connection error. This tutorial covers WordPress 2.0.1.

default wordpress error page

The database connection error occurs when WordPress tries o connect to the database but does not succeed at it. When you are first installing WordPress, it can mean that your settings are incorrect. i.e. the username/password are wrong. However, if your WordPress installation is running smoothly but for some reason MySQL goes down on your server then WordPress will show that huge “WordPress, Error Establishing a Database Connection” error page that looks nothing like the rest of your site. The error page is great when you are first setting up WordPress but it is not the most ideal for a professional website. It creates confusion for the visitor that might not even know what WordPress is. What’s worst, the web developer might not even find out for hours.

We’re going to solve this by doing a very small hack to WordPress that will tell it to show a static page instead of the default WordPress page. And we’ll also have it send an email to the administrator alerting with the error. Don’t get scared away by the word hack. Hacking is part of the WordPress culture and even encouraged. And besides, a hack is the only way around this because plugins are detected by settings stored in the database that we can not access to begin with.

STEP 1: Hack WordPress

Note: If you are running WordPress 2.0.1 you can download the hacked file here and just replace original ‘/wp-includes/wp-db.php’ and skip to step 2.

wordpress hack

Open ‘wp-includes/wp-db.php’ in a code editor. If you don’t have one, you can try the free Text Wrangler or my favorite, SKEdit. This file is the one that handles the database connections that WordPress makes. We’ll look at the last function around line 305. This function is called bail and it is called when a database connection error is found. It does what it’s name implies, it bails out and displays an error. Now, the error it shows follows up but before it gets to that point, we’ll have it show a custom page we created and have it email us the error found. Enter the code bellow as pictured above.

/* custom error page hack
shows a custom error page and emails error instead of
showing the default wordpress database error page */

$error = ( !$this->show_errors ) ? '' : $this->show_errors ;
mail('', 'WordPress Error', $error);

/* end custom error page hack */

The code Explained

This tells it to include the page dbase-error.php located in your theme folder. Replace the themename with the folder name of your theme.

$error = ( !$this->show_errors ) ? '' : $this->show_errors ;
mail('', 'WordPress Error', $error);

This emails the webmaster with the actual database error if there is one. Replace with the email address of the webmaster.

This tells the script to end and not execute anything further, like the default error it normally outputs.

STEP 2: Create the error page.

Create a custom error page that contains no WordPress code, name it ‘dbase-error.php’ and save it in your theme folder.

The whole point of this tutorial is for you to have an error page that looks like the rest of your site. But that really depends on what theme you use. In this example I started by duplicating ‘index.php’ from my theme folder and naming it ‘dbase-error.php’. Then I replaced the header, sidebar and footer code with the actual code found in the header, sidebar and footer. To do this, first open ‘header.php’ in a text editor, copy all it’s content and paste in ‘dase-error.php’ replacing < ?php get_header(); ?>. Do the same for the sidebar and footer.

Now proceed to remove all WordPress code since WordPress does not have access to your database it doesn’t know the website name or what theme to use. To help you out, I’ve included a custom error page for the default WordPress template. You can download it here and just change a few things like the website name and description. Pictured below is the one I used on the Mosaic site.

new custom error page


To test this, there’s no other way than to put your site down temporarily. First upload the new wp-db.php file then the new custom error page. Now, edit ‘wp-config.php’ so that it has the wrong database name and upload the file. Once you upload the edited config file, check your site through your browser. You should now see your new error page and receive a new email shortly alerting you there was a database error. Your can re-edit the config file and re-upload to bring your site back up.


Hopefully WordPress will create an easier way to do this, perhaps by including a new setting in the settings file. But for now, hacking it is our best choice. But do remember, when you upgrade WordPress for the next version you will need to reapply the hack.


WordPress Hack
Custom Error

18 thoughts on “Creating a custom WordPress database error page

  1. seocontest2008

    Actually, I am trying to set up a new blog and try to drop all the default database and try to replace my old blog’s database which has already posts, alot post actually. But I am having not to set up right. When tried to drop the default database then access my site, wordpress then goes installing again thus, creating the default database. I have imported my blog’s old database on it but it doesnt uses it. How to fix this one?? Please help

  2. Pingback: Custom WordPress Database Error - Derek Punsalan - 5ThirtyOne

  3. Pingback: How To Go Down In Style While Getting Your WordPress Blog Dugg, Reddited, Slashdotted, or Farked. « Cerita Panas

  4. Pingback: How To Go Down In Style While Getting Your WordPress Blog Dugg, Reddited, Slashdotted, or Farked. « Cerita Panas