{"id":4329,"date":"2026-09-12T15:51:09","date_gmt":"2026-09-12T10:21:09","guid":{"rendered":"https:\/\/cpanelfree.com\/blog\/how-to-serve-custom-error-pages-nginx-openlitespeed\/"},"modified":"2026-09-12T15:51:09","modified_gmt":"2026-09-12T10:21:09","slug":"how-to-serve-custom-error-pages-nginx-openlitespeed","status":"publish","type":"post","link":"https:\/\/cpanelfree.com\/blog\/how-to-serve-custom-error-pages-nginx-openlitespeed\/","title":{"rendered":"How to Serve Custom Error Pages (404, 500, 502, 503) in Nginx & OpenLiteSpeed"},"content":{"rendered":"
\n Quick Technical Answer:<\/strong><\/p>\n

\n To serve branded custom error pages in Nginx<\/strong>: Place standalone HTML files in \/var\/www\/html\/errors\/<\/code>. Inside your server {}<\/code> block, declare error_page 404 \/errors\/404.html;<\/code> and error_page 500 502 503 504 \/errors\/50x.html;<\/code>. Add a protected location block with internal;<\/code> (e.g. location ^~ \/errors\/ { root \/var\/www\/html; internal; }<\/code>). This ensures that even if your backend database or PHP-FPM daemon crashes completely, Nginx serves a polished, branded maintenance page directly from static disk.\n <\/p>\n<\/div>\n

Why Default Web Server Error Pages Harm Your Brand and SEO<\/h2>\n

When an unexpected server exception occurs\u2014such as a 502 Bad Gateway<\/strong> during an application deployment, a 503 Service Temporarily Unavailable<\/strong> during database maintenance, or a standard 404 Not Found<\/strong>\u2014the default response from raw Nginx or OpenLiteSpeed is a stark, unstyled black-and-white error banner.<\/p>\n

Default error pages create three critical business problems:<\/p>\n

    \n
  1. Immediate Visitor Drop-off:<\/strong> Confused users assume the entire company is defunct, immediately hitting the browser back button and escalating bounce rates.<\/li>\n
  2. Security Reconnaissance:<\/strong> Default error banners often disclose the underlying web server version (e.g. nginx\/1.18.0 (Ubuntu)<\/code>), helping malicious bot scanners identify unpatched vulnerabilities.<\/li>\n
  3. Lost Conversion Opportunities:<\/strong> A thoughtful custom 404 or maintenance page with search navigation, status updates, and support links keeps visitors engaged within your ecosystem.<\/li>\n<\/ol>\n

    Step 1: Creating Standalone Static Error HTML Pages<\/h2>\n

    Crucial architectural rule: Custom error pages for 500, 502, 503, and 504 must NEVER rely on dynamic PHP or external database connections.<\/strong> If MySQL or PHP-FPM is dead, a dynamic error script will crash recursively.<\/p>\n

    Create dedicated, self-contained static HTML files with inline CSS:<\/p>\n

    # Create dedicated errors directory\nsudo mkdir -p \/var\/www\/html\/errors\n\n# Create custom 404 page\nsudo nano \/var\/www\/html\/errors\/404.html<\/code><\/pre>\n
    Insert clean, branded HTML:<\/p>\n
    <!DOCTYPE html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"UTF-8\">\n    <title>Page Not Found | CpanelFree<\/title>\n    <style>\n        body { background-color: #0b0f19; color: #f8fafc; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; display: flex; align-items: center; justify-content: center; height: 100vh; margin: 0; }\n        .card { background: #161e31; border: 1px solid #23304b; padding: 45px; border-radius: 12px; text-align: center; max-width: 500px; }\n        h1 { font-size: 68px; margin: 0; color: #38bdf8; }\n        h2 { font-size: 22px; margin: 10px 0 15px 0; }\n        p { color: #94a3b8; font-size: 15px; line-height: 1.6; }\n        a { display: inline-block; background: #0284c7; color: #fff; text-decoration: none; padding: 12px 28px; border-radius: 6px; font-weight: 600; margin-top: 15px; }\n    <\/style>\n<\/head>\n<body>\n    <div class=\"card\">\n        <h1>404<\/h1>\n        <h2>Page Not Found<\/h2>\n        <p>The URL you requested could not be located. It may have been moved, renamed, or deleted.<\/p>\n        <a href=\"\/\">Return to Homepage →<\/a>\n    <\/div>\n<\/body>\n<\/html><\/code><\/pre>\n
    Similarly, create \/var\/www\/html\/errors\/50x.html<\/code> for server errors, explaining that scheduled maintenance is underway and services will resume momentarily.<\/p>\n
    Step 2: Configuring Nginx error_page Directives<\/h2>\n
    Open your site configuration file:<\/p>\n
    sudo nano \/etc\/nginx\/sites-available\/yourdomain.conf<\/code><\/pre>\n
    Add the error mapping directives inside your server { ... }<\/code> block:<\/p>\n
    server {\n    listen 443 ssl http2;\n    server_name yourdomain.com;\n    root \/var\/www\/html;\n\n    # Hide Nginx version tokens in HTTP headers & error pages\n    server_tokens off;\n\n    # Map HTTP status codes to custom error URIs\n    error_page 404 \/errors\/404.html;\n    error_page 500 502 503 504 \/errors\/50x.html;\n\n    # Protected Location for Error Pages\n    location ^~ \/errors\/ {\n        root \/var\/www\/html;\n        \n        # Security: Prevent public direct URL access to \/errors\/404.html\n        internal;\n    }\n\n    # Standard Reverse Proxy or PHP FastCGI handlers\n    location \/ {\n        try_files $uri $uri\/ =404;\n    }\n}<\/code><\/pre>\n
    The Magic of the internal Directive:<\/strong> Adding internal;<\/code> guarantees that visitors cannot manually navigate to https:\/\/yourdomain.com\/errors\/404.html<\/code> and trigger a false HTTP 200 response. Nginx only serves these pages when an internal redirect occurs from an actual error.<\/p>\n
    Step 3: Configuring Custom Error Pages in OpenLiteSpeed<\/h2>\n
    In OpenLiteSpeed or CyberPanel, configuring custom error documents can be done via the WebAdmin GUI or virtual host configuration file:<\/p>\n
    # Edit virtual host configuration in OpenLiteSpeed\nerrorpage 404 {\n  url \/errors\/404.html\n}\nerrorpage 500 {\n  url \/errors\/50x.html\n}\nerrorpage 503 {\n  url \/errors\/50x.html\n}<\/code><\/pre>\n
    In the OpenLiteSpeed WebAdmin console: Navigate to Virtual Hosts > Your VHost > General<\/strong>, scroll to Customized Error Pages<\/strong>, and click Add<\/strong> to define error code mappings.<\/p>\n
    Step 4: Testing Error Page Triggers Live<\/h2>\n
    Verify that your error pages deliver proper HTTP status codes while rendering your branded layout:<\/p>\n
    # Test 404 Page (Must return HTTP\/2 404 status code)\ncurl -I https:\/\/yourdomain.com\/non-existent-page-test-12345\n\n# Test 502 Simulation: temporarily stop backend application\nsudo systemctl stop myapp\ncurl -I https:\/\/yourdomain.com\/api\/<\/code><\/pre>\n
    The terminal should confirm HTTP\/2 404<\/code> or HTTP\/2 502<\/code> alongside the full HTML body of your custom error document.<\/p>\n
    SEO Best Practice: Preserving Correct HTTP Status Codes<\/h2>\n
    \n  CRITICAL SEO WARNING: Avoid Soft 404s!<\/strong><\/p>\n
    \n    Never redirect 404 errors to your homepage with a 301 or 302 redirect. Google flags this as a Soft 404<\/strong>, which dilutes topical crawl authority. Always ensure missing URLs explicitly return a true HTTP 404 header.\n  <\/p>\n<\/div>\n
    Frequently Asked Questions (FAQ)<\/h2>\n
    \n
    Can I style custom error pages using external CSS or CDN fonts?<\/h3>\n
    It is strongly advised to keep all CSS inline and avoid external dependencies. If your server is experiencing network connectivity issues or DNS resolution problems, external CDN stylesheets will fail to load, rendering a broken unstyled page.<\/p>\n
    How do I intercept 502 errors from a reverse proxy backend in Nginx?<\/h3>\n
    Add proxy_intercept_errors on;<\/code> (or fastcgi_intercept_errors on;<\/code> for PHP) inside your location block. This instructs Nginx to capture error codes emitted by the upstream backend and substitute your custom error_page<\/code> document.<\/p>\n<\/div>\n
    \n
    \ud83d\udd17 Recommended Related Technical Guides<\/h3>\n