Skip to content

Customize Error Pages

WSO2 Identity Server display errors, exceptions, and HTTP status codes in full detail. These are known as verbose error messages. These error messages contain technical details such as stack traces. There may also disclose other sensitive details. Attackers may fingerprint the server, based on the information disclosed in error messages. Alternatively, attackers may attempt to trigger specific error messages to obtain technical information about the server. You can avoid these situations by configuring the server to display generic, non-detailed error messages in Apache Tomcat.

The pages that should be displayed on a certain throwable exception, error or an HTTP status code are specified in the <IS_HOME>repository/conf/tomcat/carbon/WEB-INF/web.xml file. You can customize those error pages as preferred. For example, if you try to access a resource that is not available in the Carbon server (e.g., https://localhost:9443/carbon/abc), you will see the "Error 404 - Not Found" page (be sure to log in as admin to have access to that URL).

You can customize the above error message by following the instructions given below.

  1. Download and install Apache Maven.

  2. Create a Maven project using your IDE.

  3. Create a directory named "resources" inside the <PROJECT_HOME>/src/main/ directory, and then create another directory named "web" inside it.


    <PROJECT_HOME> denotes the top-level directory of your Maven project.

  4. Create a new HTML error page (e.g. new_error_404.html file) as shown below. This contains the customized error page.

            <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
            <title>404 - Error not found</title>
            <h1>Sorry, this resource is not found.</h1>
  5. Add the new_error_404.html file inside the <PROJECT_HOME>/src/main/resources/web directory.

  6. Add the following property below the <version> element in the <PROJECT_HOME>/pom.xml file.

  7. Add the following configurations inside the <plugins> element in the <PROJECT_HOME>/pom.xml file.

  8. Add the following configurations inside the <dependencies> element in the <PROJECT_HOME>/pom.xml file.

  9. Build the Maven project by executing the following command.

    mvn clean install           
  10. Once the project is built, copy the JAR file (from the <PROJECT_HOME>/target/ directory) to the <IS_HOME>/repository/components/dropins/ directory.

  11. Change the following configurations in the <IS_HOME>/repository/conf/tomcat/carbon/WEB-INF/web.xml file.



    You need to replicate this configuration, and change the values of the <error-code> and <location> elements accordingly for each new HTML error page you add.

  12. Restart WSO2 Identity Server.

  13. Access the following URL again to test the error page you customized: https://localhost:9443/carbon/abc.
    Be sure to log in as admin to have access to the URL.

    You will view the new error page with the following content: "Sorry, this resource is not found."