Issue

You want to create a custom web page to be displayed when users encounter an HTTP error in Jenkins, so they don’t see the generic Jetty error page which may disclose information you want to obscure.

Environment

• CloudBees CI (CloudBees Core)
• CloudBees CI (CloudBees Core) on modern cloud platforms - Managed controller
• CloudBees CI (CloudBees Core) on modern cloud platforms - Operations Center
• CloudBees CI (CloudBees Core) on traditional platforms - Client controller
• CloudBees CI (CloudBees Core) on traditional platforms - Operations Center
• CloudBees Jenkins Platform - Client controller
• CloudBees Jenkins Platform - Operations Center
• CloudBees Jenkins Distribution
• Jenkins LTS

Resolution

Possibly the most robust solution would be to run a separate reverse proxy, such as nginx, in front of your Jenkins instance. You could then intercept HTTP errors there and redirect users to any desired page. This solution would work independent of the servlet container use, and would not have to be re-applied after Jenkins updates. Otherwise, the following is a more manual solution that can be used. These instructions assume that you are running Jenkins using the built-in Jetty servlet container. If you are using Tomcat or another servlet container you will need to take a different approach.

At the moment, creating a custom HTTP error page requires editing the Jetty configuration that ships with the Jenkins war file/packages, and unfortunately changes to this configuration will be erased each time Jenkins is upgraded. As a result, you must be prepared to recreate the changes after each upgrade.

1. Create your custom error page HTML file in JENKINS_HOME/war. For example, create a page called custom-error.html which tells users to contact your support team if they see this page.
2. Create a backup copy of JENKINS_HOME/war/WEB-INF/web.xml. Then edit the existing web.xml file and look for this section:

<error-page>
<exception-type>java.lang.Throwable</exception-type>
<location>/oops</location>
</error-page>

1. Above this section, add the following:

<error-page>
<location>/custom-error.html</location>
</error-page>

1. Restart Jenkins.

After completing these steps, when a user browses to a page that would normally result in an error, they should see your custom error page.

References

Jetty custom error page documentation