Enabling custom 403 error docs with nginx in Plesk

Please note that in order to complete these steps you must have admin access to Plesk. As such, this will not work for Shared Hosting customers, and only applies to VPS Customers.

While you would think that enabling “Custom Error Docs” under hosting settings in Plesk, then editing the appropriate document under the /error_docs/ folder in your vhost root would do the trick, unfortunately that’s not the case. Those error documents are seemingly only loaded by Apache by default.

If you’ve specified IP allows/denies using Plesk 12+ then it’s using nginx to handle those denies. This is great for performance and resource consumption, but not great when it comes to compatibility with features initially configured for apache use, like custom error documents.

I tried placing the standard error_page directive at every level of the vhost’s nginx config and it did not work anywhere.

It turns out that Plesk treats the allow/deny rules as absolute, and – while it’s trying to serve the error document – it realizes it wasn’t supposed to be serving to that IP address and throws a secondary forbidden error. When you look at the logs, you’ll likely see entries indicating a 403 error followed by two “Forbidden by Rule” messages – that’s how you know this is what’s happening.

What you need to do to fix this is to explicitly set the Nginx error document, and explicitly allow it. 

location = /error_docs/forbidden.html {
    root /var/www/vhosts/yourdomain.tld/;
    internal;
    allow all;
}
error_page 403 /error_docs/forbidden.html;

To use this, simply insert the above code in the domain’s “Additional nginx directives” box (under Apache & Nginx settings). That box is provided only to Plesk admins.

The original solution I found was to use a separate subdomain for the error documents:

error_page 403 = @forbidden;
location @forbidden {
 return 302 http://{secondary_domain}/forbidden.html;
}

It’s still a valid option, but – if you’ve got access to the nginx rules – you may as well do option #1 and do it right!