How to Configure NGINX for Custom Error Pages

Want to improve your website’s user experience during errors? Custom NGINX error pages can help. They replace generic error messages with helpful, branded designs that guide users back to your site. Here’s how to set them up:

Why Custom Error Pages Matter: They enhance branding, reduce frustration, and keep users engaged.
Key HTTP Errors to Address: Focus on 404 (Not Found), 403 (Forbidden), 500 (Internal Server Error), 502 (Bad Gateway), and 503 (Service Unavailable).
Steps to Configure:
1. Create error pages (e.g., 404.html) with clear messages and navigation options.
2. Organize files in a dedicated /errors directory.
3. Update your NGINX configuration using the error_page directive.
4. Test with tools like curl or browser developer tools.

Quick Setup Example: Add this to your NGINX config:

error_page 404 /errors/404.html;
location ^~ /errors/ {
    internal;
    root /var/www/your-domain/public_html;
}

Custom error pages improve user retention and reinforce your site’s professionalism. Read on for detailed steps, testing tips, and troubleshooting advice.

How To Configure Nginx To Use Custom Error Pages

Nginx

Setup Requirements

Before getting started with custom error page setup, make sure you have everything you need.

System Requirements

To set up custom error pages with NGINX, you’ll need:

An active NGINX server.
Root or sudo access to edit configuration files.

Building Error Pages

Custom error pages not only help users navigate errors but also reinforce your website’s branding. Here’s how to design effective error pages and organize their files for seamless integration with NGINX.

Error Page Design Guidelines

When creating custom error pages, focus on these elements:

Clear Error Message
Clearly display the error code (e.g., 404, 500) with a short, straightforward explanation.
Brand Consistency
Match your website’s design by including your logo, color scheme, navigation menu, footer, and consistent typography. This ensures the page feels like part of your site.
Helpful Navigation Options
Add features like a "Back to Home" button, a search bar, links to popular pages, or contact options to guide users back to useful content.

Here’s a breakdown of what an effective error page should include:

Element	Purpose	Example Content
Header	Identify the error	"404 – Page Not Found"
Message	Explain the situation	"The page you’re looking for isn’t here."
Action Items	Help users navigate	Search bar and navigation links
Support	Offer assistance	Contact form or help center link

File Organization

For NGINX to serve error pages efficiently, keep your files well-organized. Here’s a suggested directory structure:

/var/www/  
└── your-domain/  
    ├── public_html/  
    │   └── errors/  
    │       ├── 404.html  
    │       ├── 500.html  
    │       ├── 503.html  
    │       └── assets/  
    │           ├── css/  
    │           └── images/

Why this structure works:

Keeps error pages separate from regular content, making them easier to manage.
Simplifies updates and maintenance.
Centralizes assets like CSS and images, ensuring they’re accessible even during server errors.
Makes NGINX configuration more straightforward.

Important: Store all error page assets (CSS, images, scripts) locally in the /errors/assets directory. This prevents issues if the main server is down and external resources can’t load.

Next, we’ll cover how to integrate these error pages into your NGINX configuration.

sbb-itb-608da6a

NGINX Error Page Setup

The error_page directive in NGINX lets you assign custom pages to specific HTTP error codes. Below is an example of how to configure this in your server block:

server {
    # Basic server setup
    listen 80;
    server_name example.com;
    root /var/www/your-domain/public_html;

    # Custom error pages
    error_page 404 /errors/404.html;
    error_page 500 502 503 504 /errors/500.html;
    error_page 403 /errors/403.html;

    # Error pages location block
    location ^~ /errors/ {
        internal;
        root /var/www/your-domain/public_html;
        allow all;
    }
}

Key Configuration Details

The internal directive ensures error pages can’t be accessed directly.
^~ gives this block priority over other location blocks.
The allow all directive ensures proper access when errors occur.

After adding these directives, you’ll need to update and test your configuration.

Updating and Testing Configuration

Test the configuration: Run sudo nginx -t. You should see "nginx: configuration test is successful."
Reload NGINX: Apply changes with sudo systemctl reload nginx.
Set permissions for the error pages:

sudo chown -R www-data:www-data /var/www/your-domain/public_html/errors
sudo chmod 644 /var/www/your-domain/public_html/errors/*.html

Tips for a Smooth Setup

Keep error pages in a dedicated directory, separate from other public content.
Use relative paths in error page HTML to ensure linked resources load correctly.
Configure error pages at the server block level to maintain consistent behavior across your site.
Test your error pages under various server conditions to confirm they work as expected.

Once these steps are complete, you can move on to testing and troubleshooting your setup.

Testing and Problem Solving

It’s important to test custom error pages under different error scenarios to ensure they work correctly. Here’s a guide to testing and fixing common issues.

Error Page Testing Steps

1. Check HTTP Status Codes

Use the following PHP script to simulate specific HTTP errors:

<?php
// Save this as test-error.php
$error_code = $_GET['code'] ?? 404;
http_response_code($error_code);
exit();

2. Test with a Browser or cURL

Run these commands to verify error responses:

# Check a non-existent page
curl -I http://your-domain.com/nonexistent-page

# Test a specific error code
curl -I http://your-domain.com/test-error.php?code=500

3. Verify Resource Loading

Use browser developer tools to ensure all resources (like images or stylesheets) load correctly. Pay attention to path resolutions.

If any of these tests fail, refer to the troubleshooting steps below.

Common Problems and Solutions

Permission Problems

If your error pages don’t display, check their file permissions:

# Check permissions
ls -l /var/www/your-domain/public_html/errors/*.html

# Fix permissions if necessary
sudo chmod 644 /var/www/your-domain/public_html/errors/*.html

Broken Paths for Resources

When images or styles fail to load, switch to absolute paths in your HTML:

<!-- Avoid this -->
<img src="../images/error-logo.png">

<!-- Use this instead -->
<img src="/images/error-logo.png">

Debugging with NGINX Logs

Check NGINX error logs for configuration issues:

# View logs in real-time
tail -f /var/log/nginx/error.log

# Search for specific error codes
grep "404" /var/log/nginx/error.log

Configuration Issues

If error pages don’t behave as expected, review your NGINX configuration:

# Example location block
location ^~ /errors/ {
    internal;
    root /var/www/your-domain/public_html;
    # Enable debug logs temporarily
    error_log /var/log/nginx/error-pages-debug.log debug;
}

Common Error Page Issues and Fixes

Problem	Cause	Fix
Blank error page	Incorrect file permissions	Set HTML file permissions to 644
502 Bad Gateway	PHP-FPM misconfiguration	Check PHP-FPM pool settings and error logs
Missing resources	Relative path issues	Use absolute paths for images, stylesheets, etc.
Infinite redirect loop	Misconfigured `error_page` directive	Add `internal` to the location block in your NGINX config

Additional Configuration Options

Expanding on the basic error page setup, let’s explore some advanced ways to customize your error handling.

Server-Side Includes for Error Pages

NGINX supports Server-Side Includes (SSI), allowing you to create dynamic error pages that adapt based on server variables.

# Enable SSI in the error pages location block
location ^~ /errors/ {
    internal;
    ssi on;
    root /var/www/your-domain/public_html;
}

You can break your error page into reusable components. For example:

<!-- header.ssi -->
<header>
    <!--# echo var="host" default="" -->
    <!--# echo var="date_local" -->
</header>

<!-- error-details.ssi -->
<div class="error-info">
    Error <!--# echo var="status" default="Unknown" -->
    Request: <!--# echo var="request_uri" default="" -->
</div>

Then, integrate these components into your error page:

<!-- 404.html -->
<!DOCTYPE html>
<html>
<head><title>404 Not Found</title></head>
<body>
    <!--# include file="header.ssi" -->
    <!--# include file="error-details.ssi" -->
    <p>The requested page could not be found.</p>
</body>
</html>

This modular approach simplifies updates and ensures consistency across your error pages.

Multi-Domain Error Pages

If you’re hosting multiple domains on one NGINX server, you can define domain-specific error pages using separate server blocks.

# Configuration for domain1.com
server {
    server_name domain1.com;

    error_page 404 /errors/domain1/404.html;
    error_page 500 502 503 504 /errors/domain1/50x.html;

    location ^~ /errors/domain1/ {
        internal;
        root /var/www/sites;
    }
}

# Configuration for domain2.com
server {
    server_name domain2.com;

    error_page 404 /errors/domain2/404.html;
    error_page 500 502 503 504 /errors/domain2/50x.html;

    location ^~ /errors/domain2/ {
        internal;
        root /var/www/sites;
    }
}

Organize your directory structure like this:

/var/www/sites/
├── errors/
│   ├── domain1/
│   │   ├── 404.html
│   │   └── 50x.html
│   └── domain2/
│       ├── 404.html
│       └── 50x.html

Additional Options for Multi-Domain Setups:

Use environment variables to further customize error pages.
Serve language-specific error pages based on the Accept-Language header.
Set fallback pages for domains that don’t match.

Here’s an example for language-specific error pages:

# Language-specific error pages
if ($http_accept_language ~* ^en) {
    set $error_page_root /errors/en;
}
if ($http_accept_language ~* ^es) {
    set $error_page_root /errors/es;
}

error_page 404 $error_page_root/404.html;

This setup keeps your error pages organized and makes it easy to manage multiple domains with tailored error handling.

Conclusion

Summary

Custom NGINX error pages can improve user experience and showcase professionalism. Setting them up requires thoughtful planning, correct configuration, and thorough testing.

Here are the main steps involved:

Organizing directories and ensuring accurate error_page configuration
Using server-side includes
Implementing error pages for multiple domains
Conducting detailed testing
Monitoring logs and making updates as needed

By following these steps, you can create error pages that reflect your brand and assist users effectively. Regular updates based on log data will keep them relevant and functional. If you need expert help, consider professional services like the ones described below.

OneNine Services

OneNine

If setting up error pages feels overwhelming, professional support can make the process seamless. OneNine specializes in optimizing website performance, with proven results like achieving load times as fast as one second.

"We trust OneNine to manage the websites for our entire portfolio of companies. They work with our team to solve problems, they’re always available when we need them, and their turnaround time is the best we’ve seen." – Matt Bodnar

OneNine offers a range of services, including:

NGINX configuration and optimization
Around-the-clock security monitoring and fast incident response
Performance improvements with daily speed tests
Real-time backups with precise restoration options
Dedicated account management with an average response time of 10 minutes

Their expertise allows you to focus on your core business while ensuring your website stays secure and runs smoothly. With a 100% uptime guarantee and robust security measures, OneNine provides reliable solutions for companies looking for professional website management.