Custom error pages - current limitations

Igor Sysoev is at
Thu Aug 21 14:04:00 MSD 2008

On Thu, Aug 21, 2008 at 11:44:04AM +0200, Luigi Perroti wrote:

> I'm rather new to nginx and I would like to have a confirmation that
> the following scenarios can't be handled with the current
> implementation.
> 1) When a client sends a request without the Host: header nginx
> returns an hardcoded 400 response.
> Actually it isn't possible to use a custom error page in this situation.
> I tried to handle this using the "root" and "error_page" directives in
> the http section but it didn't work.

The following should work:

http {

     error_page  400 /400.html;

     server {
         listen 80 default;

         location = /400.html {
             root  /path/to/page;

     server {
         listen 80;

Often the 400 error is handled in default server context.

> 2) Consider this simple config file snippet. It's from a configuration
> file with only one server, every request is passed to a fastcgi server
> which always processes the same script:
> server {
>    ...
>    location / {
>       fastcgi_pass;
>       fastcgi_param  SCRIPT_FILENAME    /script.php;
>       fastcgi_param  SCRIPT_NAME        script.php;
>       fastcgi_intercept_errors off;
>       ...
>    }
> }
> >From what you can see I want to handle all kinds of error codes from the script.
> Still there is an exception to that, the "500 Internal server error" response.
> If the fastcgi server returns this error nginx will do nothing and
> each browser will handle this situation differently.
> If I'm not mistaken there is no way for me to define a custom error
> page that will be triggered only for the 500 code.
> In fact, if I set "fastcgi_intercept_errors on;" nginx will also
> handle all the other error codes.
> Is there any workaround to handle these scenarios?

    location / {
        fastcgi_intercept_errors  on;

        error_page    502 504   /errors/502.html;
        error_page    500       /errors/500.html;

    location /errors/ {
        root  /path/to/pages;

fastcgi_intercept_errors intercepts only errors those have error_page
handlers. Other will go as is from PHP.

> Maybe having a directive in the http section that maps a certain
> status code to a static file could be useful in these situations and
> more.
> No matter what, before returning the page to the client check if the
> status code is handled by this directive. If it is simply return the
> associated file as the response body.
> Moreover it should also be possible to define an absolute path for the
> file, independently from the document root. To avoid having to mess
> with the "internal" directive.
> I suppose that when this feature is enabled performance would take a
> hit, but I'd accept this gladly for the increased versatility.
> Any consideration would be most welcome, thanks!

Igor Sysoev

More information about the nginx mailing list