Branded Error Pages in WordPress

Something that came up on a project I was working on recently is that when WordPress encounters a server error, you will get a generic message.

Default WordPress error screen when the server responds with an HTTP 500 status code.

This is generally okay, it’s not like you’ll be seeing it very often (hopefully) but I wanted to make sure if a user did see one, it wouldn’t feel completely alien to them.

As it turns out, WordPress has a simple solution. Create a file named php-error.php in the wp-content directory.

I created one with the following:

html

<h1>Woops, it broke ☹️</h1>

Now, the error page will look like this!

A custom PHP Error template in WordPress

It’s essentially an HTML file, so you can hook up your stylesheet, maybe include a brand logo, you have options!

Testing locally

Usually when you’re testing locally you’ll have WP_DEBUG switched on. To test your page, make sure WP_DEBUG is false in your wp-config.php and pop this code somewhere, I usually put it in functions.php but it doesn’t really matter.

php

<?php

throw new Error('You broke it.');

That’ll make PHP throw an error, as if something had gone wrong and you’ll be able to see your error page.