Websites
Custom Error Pages
A custom error page replaces the plain server default with your own branded HTML, while keeping the true error status so search engines still see a real 404. This guide covers adding a page for each supported code, what gets stripped for safety, and how the verification badge works.
Where Error Pages Live in KPanel
- Sign in to KPanel.
- Click Websites in the left sidebar, then click the site.
- In the site's tab strip, open Advanced, then Error pages.
The direct address is /websites/<site-id>/error-pages.
Why Bother
A default server error page is a dead end. It has no branding, no navigation, and no explanation, so a visitor who lands on one usually leaves.
A custom page turns that into a route back into the site: your logo, your typography, a sentence in your own voice, and a link home or to a search box. On a large site, mistyped and outdated URLs are a steady trickle of traffic, and a 404 page is the cheapest recovery you will ever build.
The Supported Codes
You can set a custom page for eight codes, one page per code:
| Code | Meaning | Typical cause |
|---|---|---|
| 400 | Bad Request | A malformed request |
| 401 | Unauthorized | Authentication required or failed |
| 403 | Forbidden | An access rule blocked the request |
| 404 | Not Found | Nothing exists at that URL |
| 500 | Internal Server Error | Your application failed |
| 502 | Bad Gateway | The application did not answer correctly |
| 503 | Service Unavailable | The application is down or overloaded |
| 504 | Gateway Timeout | The application took too long |
Start with 404. It is by far the most common, and it is the only one a visitor reaches through ordinary browsing rather than a fault.
The 5xx family is worth doing next, because those are the pages people see on your worst day. A calm branded page that says something went wrong and gives an email address is far better than a blank server error.
Adding a Page
- Click Add error page.
- Choose an error code from the dropdown. Codes already in use are not listed.
- Replace the sample HTML in the HTML body field with your own.
- Click Add error page.
The editor starts with a working 404 document you can edit down, which is a reasonable starting point if you just want something tidy quickly.
Writing the HTML
Supply a complete HTML document, starting with a doctype. It is served as-is, so it must stand on its own.
Some HTML is stripped before the page is ever stored, for safety:
<script>tags- inline event handlers such as
onclick - iframes
- remote stylesheets
If anything was removed, a warning tells you after saving.
Because remote stylesheets are stripped, an error page cannot pull in your site's main CSS file. Style it with inline CSS or a <style> block in the document head. This is deliberate: an error page must render when the rest of the site is broken, and a page that depends on fetching assets from a failing server will render as unstyled text at exactly the wrong moment.
Practical guidance:
- Keep it small and self-contained. Inline everything. Avoid external images. The page list shows each page's size in KB.
- Say what happened in plain words. "We could not find that page" beats "404 Not Found".
- Give a way forward. A link home, a link to your main sections, or a search box.
- Include a contact route on the 5xx pages, since the visitor cannot use the site to reach you.
- Do not use it to redirect. If a URL has moved, redirect it properly instead. See Site Redirects.
The Status Code Is Preserved
Your custom page is served with the real error status, not 200. A 404 stays a 404 all the way to the client.
This matters more than it sounds. A branded page returned as 200 is a soft 404: search engines index it as a real page, your analytics count it as a successful view, and broken links never get flagged by any tool. Because Kapsule keeps the true status, all of that continues to work correctly.
Reading the Status Badge
The Status column reports what could actually be verified, and it is deliberately honest about the limits.
| Badge | Meaning |
|---|---|
| Verified: branded page served (true 404) | We forced a 404 from outside and got your page with the correct status |
| Configured (not externally tested) | The page is applied. That code cannot be triggered from outside on demand |
| Not yet verified | The check has not run yet |
| Applied, live test inconclusive | The probe got something other than a clean 404, often because a redirect caught it |
| Got a 404 but the branded page was not served | The rule is in place but your page did not come back. Try re-saving |
Only 404 can be forced externally. Requesting a URL that does not exist reliably produces a 404, but there is no way to make a healthy server produce a genuine 500 on demand without breaking it. So the other codes report Configured rather than claiming a verification that never happened. They still serve when the error genuinely occurs.
You may also see a warning that another configuration on the server claims the same domain. Until that is resolved the error page may not apply. Contact support if you see it.
Troubleshooting a Site That Is Actually Erroring
If you are here because your site is throwing errors rather than because you want nicer pages, the page has a shortcut: the Troubleshoot with Kora button in the banner at the top.
It asks Kora, the assistant inside KPanel, to read your error logs and recent failures for this site and tell you the likely cause and how to fix it. That is a much faster first step than reading raw logs.
For the underlying performance picture, see Site Performance and APM, and for the error rate over time, see Site Traffic Analytics.
Editing and Removing
Each row has an edit button, which opens the same editor with the code fixed and the HTML loaded, and a remove button.
Removing asks for confirmation and explains the result: requests that hit that code fall back to the server default page.
Troubleshooting
My page is not showing. Confirm you are triggering the right code. A path that redirects never reaches a 404. Test with a URL that genuinely does not exist, in a private window so no cache is involved.
The page shows but looks unstyled. Your stylesheet was stripped as a remote asset. Inline the CSS.
My tracking script is missing. Scripts are stripped by design. There is no way to run JavaScript from a custom error page here.
All codes already have a page. Every one of the eight is in use. Edit an existing page instead of adding another.
The badge says the branded page was not served. Re-save the page. If it persists, and no domain conflict warning appeared, open a ticket.
Related Pages
- Site Redirects to stop the 404 happening in the first place.
- Site Traffic Analytics to see how many 4xx and 5xx responses you are actually serving.
- Password-Protecting a Site, which produces 401 responses by design.