Nginx - Customizing 404 page

Nginx - Customizing 404 page

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Nginx - Customizing 404 Page for PHP Applications

When deploying a stack involving Nginx and PHP via FastCGI, you likely noticed that missing files behave differently than static HTML requests. If you request a non-existent .html file, the server returns the standard generic 404 error page provided by your web server configuration. However, when requesting a missing PHP script or any dynamic resource, Nginx forwards the request to the PHP-FPM process. The PHP interpreter executes, checks for the script path, and if it cannot find the file, outputs the default message: "No input file specified."

This behavior is not a bug; it is the result of how the PHP-FPM daemon handles execution requests versus static file serving. To customize this experience, you must understand that simply placing an errors/404.html file in your document root will not suffice for dynamic routes. The 404 page for dynamic content needs to be generated by a specific handler within Nginx before the request reaches PHP, or handled entirely on the PHP side after the script is invoked but fails.

Handling Static vs. Dynamic 404s

The cleanest architectural approach separates concerns between static assets and dynamic logic. If your application framework (like Laravel) expects to handle routing errors internally, you often want Nginx to return a custom status code for non-existent files while letting PHP take over the rendering.

You can achieve this by configuring an error_page directive in your Nginx site configuration. This tells Nginx to intercept 404 responses and serve a specific file or script instead of the default output.

server {
    listen 80;
    server_name example.com;
    root /var/www/html;

    # Intercept 404s for static files
    error_page 404 =404 /custom_404.php;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
}

In this configuration, when a request for a non-existent file occurs, Nginx does not immediately generate a default 404. Instead, it triggers the try_files directive logic first. If $uri and $uri/ fail, the request falls back to /index.php. However, if you want to ensure a custom page loads even for static assets that don't exist, you might need to adjust how error_page interacts with your location blocks.

A more robust pattern often involves directing all 404s to a dedicated script:

location @missing {
    root /var/www/html;
    try_files $uri $uri/ =404;
}

error_page 404 = @missing;

Here, the @missing location block attempts to serve the requested file. If it fails again (which it will for a missing file), Nginx returns a 404. You can then set index.php as the fallback within that block if you want PHP to render the final response. This ensures that your application's logic, rather than Nginx's default text output, generates the HTML.

The "No Input File Specified" Message

The specific error message "No input file specified" appears because the FastCGI process successfully executed a script (often index.php or a route handler) which then attempted to include a non-existent file or view. This is a logic flow issue within your PHP application, not necessarily a configuration failure in Nginx.

To customize this specific message, you must catch the exception or error state inside your PHP entry point. For example, in a standard Laravel setup, this often happens when a route is defined but the controller returns a 404, or when the framework attempts to load a non-existent Blade template.

You can override the default output by configuring Nginx to serve a static custom page for any 404 response, regardless of whether it originated from PHP or Nginx itself:

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

By setting internal; on the location block, you prevent external users from directly accessing this error file via a browser. This ensures that whenever a 404 occurs—whether it's a missing static file or a dynamic route failure—Nginx serves your custom HTML defined in /errors/404.html.

Trade-offs and Considerations

Implementing a unified 404 strategy has implications for debugging. If you hide the "No input file specified" error behind a generic HTML page, it becomes harder to trace why a dynamic route failed during development. In production, this is usually desirable for security and aesthetics, but in local environments, you might want to disable try_files fallbacks or remove the error_page directive temporarily to see the raw PHP errors.

Another consideration is caching. If your custom 404 page is served by Nginx, ensure that any dynamic content within it (like a link back home) isn't inadvertently cached with an aggressive cache header unless you intend for it to be static.

Finally, if you are using a framework like Laravel, remember that the framework often has its own exception handling middleware that generates 404 pages. If your Nginx configuration forces a redirect to /errors/404.html before the request hits the application, Laravel's exception handling might never execute. You must weigh whether you want the server-level error page or the application-level error page for missing resources. Typically, application-level errors are preferred as they can include framework-specific breadcrumbs and styling consistent with your UI.

For more advanced routing strategies in PHP applications, consider visiting https://laravelcompany.com to see how modern frameworks handle error rendering out of the box.

Our network