When a 404 error is encountered, a 404.php template file can be used to render a custom error message. This is documented in the Template Hierarchy article.

My aim is to create custom error pages for 401, 403 and 500 errors. I've tried creating 401.php, 403.php and 500.php files in my theme's directory but this doesn't work.

How can I create custom 401, 403 and 500 error pages in WordPress?


1 Answer 1


Error pages are served up via .HTACCESS, if you are using Apache you would use the ErrorDocument directive and add the status and URL to it.

So it would look like this in your .htaccess file:

ErrorDocument 401 http://yourwebsite.com/error-401
ErrorDocument 403 http://yourwebsite.com/error-403
ErrorDocument 500 http://yourwebsite.com/error-500

You could use the following function below. This will dynamically add what is needed to the HTACCESS file for you or you could manually do it.

1. Add Pages:

You would then need to go into your Dashboard and create the Pages like any normal page ('Dashboard' > 'Pages' > 'New'). They can be titled what ever you wish, just make sure the slug is the same as in the function below (Slug: error-401, error-403, error-404, error-500). Also you can use page template to create whatever layout and style you want for these specific pages. Follow WordPress Codex instructions for this.

2. Add Function:

// Create Custom Error Pages in WordPress using HTACCESS
function royal_custom_error_pages() {

    // Get HTACCESS path & dynamic website url
    $htaccess_file = '.htaccess';
    $website_url = get_bloginfo('url').'/';

    // Check & prevent writing error pages more than once
    $check_file = file_get_contents($htaccess_file);
    $this_string = '# BEGIN WordPress Error Pages';

    if( strpos( $check_file, $this_string ) === false) {

    // Setup Error page locations dynamically
    $error_pages .= PHP_EOL. PHP_EOL . '# BEGIN WordPress Error Pages'. PHP_EOL. PHP_EOL;
    $error_pages .= 'ErrorDocument 401 '.$website_url.'error-401'.PHP_EOL;
    $error_pages .= 'ErrorDocument 403 '.$website_url.'error-403'.PHP_EOL;
    $error_pages .= 'ErrorDocument 404 '.$website_url.'error-404'.PHP_EOL;
    $error_pages .= 'ErrorDocument 500 '.$website_url.'error-500'.PHP_EOL;
    $error_pages .= PHP_EOL. '# END WordPress Error Pages'. PHP_EOL;

    // Write the error page locations to HTACCESS
    $htaccess = fopen( $htaccess_file, 'a+');
    fwrite( $htaccess, $error_pages );


add_action('init','royal_custom_error_pages'); // This will run the function everytime, not ideal!

// register_activation_hook( __FILE__, 'royal_custom_error_pages' ); // Using a plugin, runs only once!


When moving your website or changing URL structure

The thing to remember with the above function is although it will check to see if the ErrorDocument directives already exist before writing them to your HTACCESS file it will not rewrite the ErrorDocument directives should you change or move your blog to reflect the updated page locations. You would need to delete the existing ErrorDocument directives in your HTACCESS file first and then rerun this function to create the new directives.

Correct Hook to fire the function ONLY ONCE

The other thing to note is this function, using the init action will run every time your pages load which is super unnecessary and wasteful so I would suggest adding it to a plugin and using the register_activation_hook rather so it only fires once on plugin activation

File Permissions

Also it is imperative that your .htaccess is writable when using the above function, so make sure it has the correct file permissions, something like CHMOD777.

  • Not sure how this is suppose to work, did the edits manually to the .htaccess file, but this does not work. I am trying to do this on localhost and this should be possible on localhost, since I have access to everything, the server, and client. But why is this not working? Apr 26, 2016 at 3:34
  • @SolomonClosson, perhaps you can try using the plugin I wrote for this, it will do everything for you and follows the code above exactly :). Official WordPress.Org Plugin
    – Matt Royal
    Apr 26, 2016 at 8:04
  • @MattRoyal The function works great and I am using it to create other htaccess rules. How can I make the rules be inserted at the very top of the file, above the default wp htaccess rules please? At the moment the rules are added at the bottom of the htaccess file. Thank you.
    – lowtechsun
    Feb 12, 2018 at 15:27
  • 2
    I disagree with the solution: 1- YOU SHOULD NOT 777 anything on a webserver! That's just a bad practice in general and leads to major security holes. 2- You are adding a file write on every request to the website, being a write action it will create a lock on the file allowing only one write at the time you will be reducing the number of requests you and respond simultaneously. 3- A website should not have dependencies of the server where it runs, if it gets migrated to a system where nginx is used for instance, it will stop working as expected. ...continues Sep 10, 2019 at 9:41
  • 4- There are cleaner ways of grabing errors stackoverflow.com/a/34619308/768516 Sep 10, 2019 at 9:45

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.