Skip to main content
Mapagam

Handling Error Pages

1. Configuring Error Pages

Directive Values Description
error_page 404 /404.html Defines the page to serve for a specific error code
error_page 500 502 503 /error.html Maps multiple error codes to a single page
error_page 404 = /custom-404.html Redirects to a new location with the same status code

Example: Basic Error Page Configuration

server {
    listen 80;
    server_name example.com;

    error_page 404 /404.html;
    error_page 500 502 503 /error.html;

    location = /404.html {
        internal;
    }

    location = /error.html {
        internal;
    }
}

Example: Custom Redirect for 404 Errors

server {
    listen 80;
    server_name example.com;

    error_page 404 =302 /redirect-to-home;

    location = /redirect-to-home {
        return 302 https://example.com;
    }
}

2. Setting Custom Error Pages

Directive Values Description
error_page 404 /404.html Defines the page to serve for a specific error code
error_page 500 502 503 /error.html Maps multiple error codes to a single page
error_page 404 = /custom-404.html Return the page with a 404 status code (not 200)

Example: Custom 404 Page

server {
    listen 80;
    server_name example.com;

    error_page 404 /custom-404.html;
    location = /custom-404.html {
        internal;
    }
}

Example: Multiple Error Pages

server {
    listen 80;
    server_name example.com;

    error_page 404 /errors/404.html;
    error_page 500 502 503 /errors/server-error.html;
}

3. Using Internal Redirects

Directive Description Example
error_page Defines the page to serve when an error occurs. Can use internal redirects. error_page 404 /404.html;
error_page Can also define multiple error codes to redirect to the same page. error_page 404 500 502 /error.html;
error_page Use = to prevent internal redirects and serve static content. error_page 404 = /static/404.html;

Example: Internal Redirect for 404 Errors

server {
    listen 80;
    server_name example.com;

    error_page 404 /custom-404.html;
    location = /custom-404.html {
        internal;
    }
}
Note: The internal directive ensures that the location block is only accessible internally, preventing direct access via URL.

4. Handling Multiple Error Codes

Error Code Description Handler Notes
400 Bad Request error_page 400 /errors/400.html; Client sent malformed request
401 Unauthorized error_page 401 /errors/401.html; Authentication required
403 Forbidden error_page 403 /errors/403.html; Access denied
404 Not Found error_page 404 /errors/404.html; Resource not found
500 Internal Server Error error_page 500 /errors/500.html; Server-side error
502 Bad Gateway error_page 502 /errors/502.html; Proxy server received invalid response
503 Service Unavailable error_page 503 /errors/503.html; Server overloaded or under maintenance
504 Gateway Timeout error_page 504 /errors/504.html; Proxy server timed out

Example: Custom Error Page Configuration

error_page 404 /errors/404.html;
error_page 500 502 503 504 /errors/generic.html;

location = /errors/404.html {
    internal;
}

location = /errors/generic.html {
    internal;
}
Note: The internal directive ensures that the error pages are only accessible internally and not directly requested by clients.

5. Setting Error Page Response Code

Directive Values Description
error_page 404 /404.html Sets the error page for 404 errors
error_page 500 502 503 /error.html Maps multiple error codes to a single page
error_page 404 =200 /success.html Changes the response code to 200 for 404 errors

Example: Custom 404 Page with Redirect

error_page 404 /custom-404.html;
location = /custom-404.html {
    internal;
}

Example: Change 500 Error Code to 200

error_page 500 =200 /success.html;

6. Using Named Locations for Errors

Directive Description Example
error_page Defines the error page to be used for specific HTTP status codes. error_page 404 /404.html;
error_page Can also be used to redirect to a named location using @name. error_page 500 502 503 504 @error;

Example: Using Named Locations for Error Handling

location / {
    proxy_pass http://backend;
    error_page 502 503 504 @error;
}

location @error {
    return 503 "Service Unavailable";
}
Note: Named locations are defined with an @ prefix and can be used in directives like error_page to handle errors with custom logic or responses.

7. Proxying Error Pages

Directive Values Description
error_page 404 /404.html Defines the page to serve for a specific error code
error_page 500 502 503 /error.html Maps multiple error codes to a single page
error_page 404 = /custom-404.html Forces a 200 status code for the error page

Example: Basic Error Page Proxying

server {
    listen 80;
    server_name example.com;

    error_page 404 /404.html;
    error_page 500 502 503 /error.html;

    location = /404.html {
        internal;
    }

    location = /error.html {
        internal;
    }
}

Example: Proxying to Upstream Server

server {
    listen 80;
    server_name example.com;

    error_page 502 /proxy-error.html;

    location = /proxy-error.html {
        proxy_pass http://backend-server;
    }
}
Note: The internal directive ensures that the error pages are only accessible internally and not directly requested by clients.
Warning: When proxying error pages, ensure that the upstream server is configured to handle the error page requests properly.

8. Configuring Recursive Error Pages

Recursive error pages in Nginx allow you to define custom error pages that can themselves trigger error handling, creating a cascading effect for error management. This is useful for providing fallback content or logging errors when the primary error page fails to load.

Directive Values Description
error_page 404 /404.html Defines the error page for 404 errors. Can be extended to include recursive handling.
error_page 500 502 503 504 = /error.html Maps multiple error codes to a single error page, useful for grouping similar errors.

Example: Basic Recursive Error Page Configuration

server {
    listen 80;
    server_name example.com;

    error_page 404 /404.html;
    error_page 500 502 503 504 /error.html;

    location = /404.html {
        internal;
    }

    location = /error.html {
        internal;
    }
}
Note: The internal directive ensures that the error pages are only accessible internally and not directly requested by clients.

Example: Recursive Error Handling with Custom Logic

server {
    listen 80;
    server_name example.com;

    error_page 404 /custom-404.html;
    location = /custom-404.html {
        internal;
        proxy_pass http://backend/error-handler;
    }

    error_page 500 502 503 504 /fallback-error.html;
    location = /fallback-error.html {
        internal;
        return 503 "Service Unavailable";
    }
}

9. Setting Default Error Responses

Directive Values Description
error_page 404 /404.html Sets the page to display for 404 errors
error_page 500 502 503 504 /5xx.html Maps multiple error codes to a single page
error_page 404 = /custom-404.html Return the custom page with 404 status code

Example: Basic 404 Error Page

server {
    listen 80;
    server_name example.com;

    error_page 404 /404.html;
    location = /404.html {
        internal;
    }
}

Example: Multiple Error Pages

server {
    listen 80;
    server_name example.com;

    error_page 404 /errors/404.html;
    error_page 500 502 503 504 /errors/5xx.html;

    location = /errors/404.html {
        internal;
    }

    location = /errors/5xx.html {
        internal;
    }
}

10. Logging Error Details

Directive Description Default Notes
error_log Specifies the file to which error logs are written error_log logs/error.log Can be specified multiple times for different log levels
error_log_format Defines a custom format for error logs default Available since 1.25.0
error_log_level Sets the minimum level of errors to log error Valid levels: debug, info, notice, warn, error, crit, alert, emerg

Example: Configuring Error Logging

error_log /var/log/nginx/error.log warn;
error_log /var/log/nginx/error_custom.log info;

# Custom log format (since 1.25.0)
error_log_format custom_log_format '[$time_local] [$status] [$request] [$remote_addr]';

error_log /var/log/nginx/custom_error.log custom_log_format;

Example: Log Level Configuration

error_log /var/log/nginx/error.log debug;

# Log only warnings and above
error_log /var/log/nginx/warnings_only.log warn;
Note: The error_log directive can be used at multiple levels (main, server, location) and will inherit from higher scopes if not overridden.

Error Log Levels

  • debug: Detailed information for diagnosing problems
  • info: General information about the operation
  • notice: Normal but significant conditions
  • warn: Warning conditions that are not errors
  • error: Error conditions (default level)
  • crit: Critical conditions
  • alert: Alert conditions requiring immediate action
  • emerg: System is unusable

11. Implementing Custom Error Templates

Example: Basic custom error page setup

error_page 404 /errors/404.html;
error_page 500 502 503 504 /errors/5xx.html;

location /errors/ {
    internal;
}
Error Code Template Path Description
404 /errors/404.html Page not found error
500 /errors/5xx.html Internal server error
502 /errors/5xx.html Bad gateway error
503 /errors/5xx.html Service unavailable
504 /errors/5xx.html Gateway timeout
Note: The internal directive ensures that error pages are only accessible internally and not directly requested by clients.

Example: Custom 404 page with dynamic content

error_page 404 /errors/404.html;

location = /errors/404.html {
    internal;
    add_header Content-Type text/html;
}

Example: Using variables in error pages

error_page 404 /errors/404.html;
location = /errors/404.html {
    internal;
    return 404 "<html><body><h1>Page not found</h1><p>Requested URL: $uri</p></body></html>";
}

12. Handling Upstream Errors

Directive Description Default Notes
error_page Defines the error page to serve for specific HTTP status codes. None Can be used multiple times for different error codes.
error_page 404 = /404.html Redirects 404 errors to a custom page. None Can use = to return the page as a response.
error_page 500 502 503 = /error.html Maps multiple error codes to a single page. None Useful for grouping similar errors.

Example: Custom Error Page for 502 Errors

location / {
    proxy_pass http://backend;
    error_page 502 = /error_502.html;
}

Example: Default Error Page for All Errors

error_page 500 502 503 504 /error.html;
location / {
    proxy_pass http://backend;
}
Note: The error_page directive can be used at any level (main, server, location) and will override previous definitions in higher scopes.
Warning: Avoid infinite loops by ensuring that error pages do not themselves cause errors.
Error Code Description Common Cause Suggested Action
502 Bad Gateway Backend server is not responding Check backend service status and logs
503 Service Unavailable Backend is overloaded or down Implement load balancing or retry logic
504 Gateway Timeout Proxy timeout waiting for backend Adjust proxy timeouts or increase backend capacity

Was this article helpful?

Related Cheat Sheets