To show an app-specific 404 page on Dokku, add an error_page 404 /404.html; mapping and a matching internal location to the app’s Nginx configuration. For a Git deployment, manage that configuration in nginx.conf.sigil; for a host-controlled exception, use the app’s /home/dokku/APP/nginx.conf.d/*.conf include directory. Then validate the generated configuration, reload Nginx, and request a nonexistent URL while checking that the response body is yours and the status remains 404.
Antihost offers VPS plans with one-click Docker, NVMe storage and a 14-day free trial.
Dokku’s built-in 404 page is shared across applications. Changing it globally is different from branding one application, so choose the configuration scope before editing anything.
As an Amazon Associate I earn from qualifying purchases.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteHow Dokku handles 404 responses
Dokku places shared custom error pages under /var/lib/dokku/data/nginx-vhosts/dokku-errors. The shared area covers three classes of responses: non-404 4xx errors, 404 errors, and 5xx errors. Because those files are shared, a change there affects the Dokku installation rather than only one application.
That is why a newly deployed app commonly displays Dokku’s generic 404 page. The request is reaching Dokku’s generated Nginx server, but no app-level rule has replaced the shared error document. An app-specific design requires an app-specific Nginx override.
#1 Best Overall
Nginx’s error_page directive maps an error to another URI or document. The official Nginx guidance describes it this way: “With the error_page directive, you can configure NGINX Plus to return a custom page along with an error code, substitute a different error code in the response, or redirect the browser to a different URI.” The directive handles an error produced by Nginx or returned by a proxied server; it does not create the 404 condition.
When a shared Dokku page is the better choice
The shared directory is appropriate when every application should use the same maintenance, branding, or support message. It is also the place to inspect when you want to understand why an untouched app returns Dokku’s standard response. However, a global edit has a broad blast radius: one change can alter the experience of unrelated apps and may be overwritten or require review during a Dokku upgrade.
Use the shared location only when that organization-wide behavior is intentional. If one app needs a different logo, navigation, language, or support contact, leave the shared files alone and add an app-level override. Keep a copy of any global customization in your host configuration management so a replacement server can be rebuilt consistently.
Choose the right configuration scope
| Approach | Where it is managed | Scope | Portability and maintenance |
|---|---|---|---|
| Shared Dokku error page | /var/lib/dokku/data/nginx-vhosts/dokku-errors |
All applications using the shared page | Centralized, but unsuitable when each app needs different branding |
nginx.conf.sigil |
Application source tree, or the image’s WORKDIR |
One application | Repository-managed and repeatable across deployments; must track the installed Dokku template |
nginx.conf.d/*.conf |
On the Dokku host at /home/dokku/APP/nginx.conf.d/ |
One application | Convenient for operator-managed changes, but not stored with application source and therefore less portable |
Use nginx.conf.sigil when the rule belongs with the application and should travel through version control and deployment automation. Use nginx.conf.d when an administrator intentionally owns the setting outside the repository, such as a host-specific policy.
Check prerequisites before changing Nginx
- Know the Dokku application name. In the commands below, replace
APPwith that name. - Confirm that the app has a running
webprocess. An undeployed app, an app with nowebprocess type, or an app whose web processes are stopped receives a minimal generated configuration that returns502. That is a separate failure from an application URL returning404. - Decide where the static error document will live. The path in the Nginx
rootoraliasdirective must point to a real file that Nginx can read in your deployment model. - Obtain the Nginx template shipped with the installed Dokku release. Dokku warns that its default template can change between releases, so an override should be based on the version actually installed on the server.
Create the custom 404 document
Make a complete static document such as 404.html. Include the application name, a short explanation, a link back to a known-good page, and any essential navigation that does not depend on JavaScript. Keep asset references usable from the error URI: root-relative paths such as /assets/site.css are generally safer than a relative path that would resolve below a nonexistent URL.
The file must be available at the filesystem location selected by the Nginx root or alias. A common pattern is an application-owned public directory, represented below by /home/dokku/APP/public/404.html. That path is an example, not a universal Dokku document root. If your files exist only inside a container, adapt the location to the way that deployment exposes static files instead of copying this path unchanged.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Keep the custom location private unless you deliberately want visitors to request it directly. The internal directive allows Nginx to use the URI for internal error handling while rejecting ordinary external requests to that URI.
Configure an app-specific page with nginx.conf.sigil
For Git-based deployments, Dokku looks for nginx.conf.sigil at the root of the source tree. For git:from-image and git:load-image deployments, it looks in the Docker image’s WORKDIR. A monorepo can select a different repository-relative location with the Dokku setting shown later.
- Start with the installed template. Do not replace the generated file with a minimal server block copied from an unrelated example. Preserve the release-matched proxy, upstream, SSL, logging, and Dokku-specific directives, then add the 404 handling in the appropriate server context.
- Add the error mapping. At server level, map status 404 to the custom URI with
error_page 404 /404.html;. - Add an exact-match location. Serve only the intended file, point
rootoraliasat the directory that actually contains it, and useinternalunless public access is intentional. - Deploy the application. Dokku must render the template before the running Nginx configuration can change.
- Inspect the rendered result. Use
dokku nginx:show-config APPand confirm that both the mapping and the location survived template rendering.
The following is a conceptual pattern showing the two directives together:
server {
# Keep the proxy, upstream, SSL, and other directives
# from the template shipped with this Dokku release.
error_page 404 /404.html;
location = /404.html {
root /home/dokku/APP/public;
internal;
}
}This is not a drop-in replacement for Dokku’s generated server. The application document root, permissions, and whether the file is on the host or served by the container must match your deployment. If you use alias instead of root, verify the URI-to-file mapping carefully; an incorrect trailing slash or path can produce another 404.
Recommended Free Tools
Set the template path in a monorepo
If the template is not at the repository root, set a repository-relative path before deploying:
dokku nginx:set APP nginx-conf-sigil-path .dokku/nginx.conf.sigilThe value is relative to the repository. Commit the file at that location, deploy again, and inspect the generated configuration. This setting is useful when several services share one repository and the Dokku template belongs in a dedicated deployment directory.
Use a host-managed nginx.conf.d include instead
Dokku also includes files from /home/dokku/APP/nginx.conf.d/*.conf in the generated server block. Create the file on the Dokku host; it is not copied from the application repository. A host include can contain the same server-level mapping and exact-match location:
error_page 404 /404.html;
location = /404.html {
root /home/dokku/APP/public;
internal;
}Use this route when an operator intentionally controls the setting outside application source. Its trade-off is repeatability: a new server or a rebuilt host will not receive the include unless you provision it separately. Keep a record of the host file and its intended application so an upgrade does not silently remove the behavior.
Understand the request flow and status code
A missing route may be rejected by Nginx before proxying, or the upstream application may return a 404 that Nginx then handles. In both cases, error_page selects the configured URI; it is not a route declaration inside the application. The internal subrequest should resolve to the static file without being sent back to the same upstream location.
Test the body and status separately. A page that looks correct but returns 200 can break monitoring, caches, search indexing, and client-side error handling. Likewise, a redirect may hide the original error. Keep the mapping as a representation change and investigate any status replacement in the surrounding template or application logic.
Validate and reload Nginx safely
After changing a host include, run:
dokku nginx:reloadDokku documents that this command validates the current Nginx configuration and, when valid, signals Nginx to reload without restarting the running process. If validation fails, Dokku exits without reloading, so the last valid configuration remains active.
Use the app inspection commands while diagnosing a change:
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsRank #3
dokku nginx:show-config APP
dokku nginx:validate-config APPnginx:show-config displays the generated configuration for the app. nginx:validate-config checks app configurations and also supports --clean, which removes invalid app configurations. Use that option deliberately; it is a cleanup operation, not a routine validation flag.
Test the result without losing the 404 status
- Choose a URL that definitely does not exist, for example a random path under the app’s hostname.
- Request it with a browser or an HTTP client.
- Check the response body for the custom document.
- Check the HTTP status independently and confirm it is still
404, not200or a redirect. - Check a known valid route to ensure ordinary application traffic still reaches the upstream.
An internal error-page mapping should change the representation of the error, not make the missing resource appear successful. If an application endpoint or redirect intentionally changes the status, inspect the rendered configuration and the application response path rather than assuming the custom file is at fault.
Troubleshoot the common failure modes
Dokku still shows its generic 404 page
- Run
dokku nginx:show-config APP. Iferror_page 404 /404.html;is absent, Dokku did not load the template or include you edited. - For a Git deployment, verify that
nginx.conf.sigilis in the source root, or thatnginx-conf-sigil-pathpoints to the correct repository-relative file. - For an image deployment, verify that the file is in the image’s
WORKDIR. - If you used a host include, confirm the file is on the Dokku host under the correct app directory and has a
.confsuffix. - Reload after the change and inspect the rendered server rather than testing an unrendered source file.
The request returns 502 instead
A 502 from Dokku commonly indicates that the app has no running web process, has not been deployed, or its web processes are stopped. Start by fixing the process state. Dokku generates a minimal 502 configuration for that condition and replaces it when web processes are running; changing a 404 mapping will not repair an unavailable upstream.
The custom location produces another 404
- Confirm that the file exists exactly where the configured
rootoraliasresolves/404.html. - Check that the Nginx worker can read the directory and file.
- Check whether the document is actually inside a container while the location points to a host path, or vice versa.
- Use an exact location for the error document and avoid a rule that sends the internal request back through the same failing proxy.
The configuration refuses to reload
Run dokku nginx:validate-config APP and read the reported file and line. Typical causes include placing a directive in the wrong context, an unmatched brace, a malformed path, or an override that no longer matches the installed Dokku template. Correct the source or host include, validate again, and only then reload.
Free tools Windows power users keep installed
One-click scans. No signup required.
The page is publicly reachable when it should not be
Keep internal in the exact-match location. Nginx will still use the URI for an internally generated error, while a direct client request is denied. Remove internal only when direct access to the document is an intentional part of the application.
The body is custom but the status is 200
Inspect the complete error flow. The custom location should be reached through error_page, and the original missing-resource status should remain 404. A separate application route, redirect, or proxy response may be replacing the status. Test with a deliberately nonexistent URL and verify status and body independently.
Read the Nginx logs when the result is still unexpected
Dokku provides commands for the app’s Nginx logs:
dokku nginx:access-logs APP
dokku nginx:error-logs APPUse the access log to confirm which URL and status were returned. Use the error log to identify file permission failures, an invalid internal redirect, or an upstream problem. A log entry showing a request for the nonexistent URL followed by a file-open error usually points to the custom document path; an upstream connection error points to the app’s web process instead.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Keep overrides upgrade-safe
Dokku’s generated Nginx template is release-sensitive. Before upgrading Dokku, compare your nginx.conf.sigil override with the template shipped by the new release and preserve any new required directives. A minimal hand-written server block may work temporarily but can omit changes needed for proxying, TLS, buffering, or process discovery.
Rank #4
Repository-managed templates are easier to review and reproduce, but they move with application deployment and therefore need version control and release testing. Host-managed includes are useful for an operator’s local policy, but they must be recreated during host replacement and audited separately from application code.
Recommended operating checklist
- Decide whether the page is global or app-specific.
- For an app-specific page, prefer
nginx.conf.sigilwhen the rule should be versioned with the app. - Base the override on the template shipped with the installed Dokku release.
- Map
404witherror_page 404 /404.html;. - Serve the file from a verified, readable path and keep the location
internalunless direct access is intentional. - Confirm a running
webprocess before diagnosing a 404 customization. - Inspect with
dokku nginx:show-config APP. - Validate with
dokku nginx:validate-config APP, avoiding--cleanunless you deliberately want invalid configurations removed. - Reload with
dokku nginx:reload. - Request a nonexistent URL and verify both the custom body and the unchanged 404 status.
Why this arrangement works
The error mapping stays at the generated server level, where Nginx can handle failures produced before a request reaches the application as well as qualifying errors returned by a proxied server. The exact-match location gives Nginx a deterministic document target, while internal prevents that target from becoming an unintended public endpoint. Dokku remains responsible for generating and reloading the surrounding proxy configuration, so the override changes only the error behavior you intend to own.
Frequently Asked Questions
Where should I put error_page 404 in Dokku?
Put error_page 404 /404.html; in the server-level portion of an app’s release-matched nginx.conf.sigil, or in a host file under /home/dokku/APP/nginx.conf.d/. Do not insert it into an unrelated application configuration block or replace Dokku’s complete generated template.
Why does Dokku keep showing its default 404 page?
Inspect dokku nginx:show-config APP. If the mapping is missing, check the Git source root, the configured monorepo path, the image WORKDIR, or the host include location and .conf suffix. Deploy or reload after correcting the source, then inspect the rendered server again.
Can I change the 404 page for only one app?
Yes. Use an app-specific nginx.conf.sigil or an app directory include. The shared files in /var/lib/dokku/data/nginx-vhosts/dokku-errors apply broadly and are intended only when the same page should serve multiple applications.
Should the custom error location be marked internal?
Usually yes. internal lets Nginx reach the URI during error handling while rejecting direct client requests. Remove it only when intentionally making the document publicly requestable.
Why am I getting 502 instead of 404?
Dokku uses a minimal 502 configuration when the app is undeployed, has no web process type, or its web processes are stopped. Restore a running web process first; a 404 mapping cannot repair an unavailable upstream.
How do I verify that the custom page still returns 404?
Request a deliberately nonexistent URL, inspect the response body, and check the HTTP status independently. Confirm it is 404, not 200 or a redirect, and test a valid route to ensure normal proxying still works.
The Bottom Line
For a portable, app-specific Dokku 404 page, keep the release-matched Nginx override in nginx.conf.sigil, map 404 to a readable static document with an internal exact-match location, then inspect, validate, reload, and test both body and status. Use nginx.conf.d only when host-level ownership is deliberate, and remember that a stopped web process produces a separate 502 condition.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
