IBM Support

Redirecting to a custom error page when HTTP 404 Not Found encountered on non-URL resources



IBM WebSphere Portal is successfully installed and configured. End-users will occassionally mistype a direct link on my portal site, such as "http:// portalserver:10040/ wps/noimage.jpg," where the noimage.jpg file does not exist. When doing so, users are redirected to the Portal login page. How do you redirect them to a specific custom error page instead of the Portal login page?


Non-URL resources are handled and processed within the security layer WebSphere Application Server (WSAS). These definitions are specified in the web.xml file in the wps.ear file. A modification in the Portal configuration is required to allow a specific custom error page to be displayed.

Note: The context of this Technote is specific to non-URL resources. To redirect to a specific homepage in the event of a bogus or nonexistent URL, please refer to How To redirect to a specific homepage when HTTP 404 Not Found encountered on URLs.


This Technote focuses specifically on HTTP 404 error code handling.

Diagnosing The Problem

Attempt to access a nonexistent resource via a direct link to the Portal server, e.g:http://portalserver:10040/wps/noimage.jpg

Observe an error 404 is displayed on the webpage.

Resolving The Problem

1) Open a command-prompt or terminal session for the Portal server.

2) Create a temporary directory to which the logged-in user has read and write access to. Or an existing temporary directory (/tmp) may be used if the user has appropriate privileges to it.

    - Throughout this example, the /tmp and /tmp/wps_expanded directories will be utilized.

3) Navigate to the <was_profile_root>/bin directory.

4) Use the command to export the wps.ear file per the Portal 6.1 Infocenter, e.g.

*Note, if the operation times out, open the soap.client.props in the <wp_profile>/properties directory, and change the parameter to a value of 6000, save the file, and retry the export.

5) Expand the wps.ear file into the temporary directory utilizing the EARExpander.(bat|sh) utility. See the references section of this document for the exact command to run based on your version of Portal.

6) Navigate to the expanded directory. Locate the web.xml file under /tmp/wps_expanded/wps.war/WEB-INF/.

7) Backup the web.xml file.

8) Open the web.xml file in a text editor.

9) Locate the following entry in web.xml:


10) Modify as follows:

11) Save the web.xml file.
12) Portal v8 and higher: Repeat steps #6-#10 for the web_merged.xml file, located in the same directory as web.xml

13) Navigate to the /tmp/wps_expanded/wps.war/ directory.

14) Create a directory named "html". Navigate to that directory.

15) Create a directory named "error404". Navigate to that directory.

16) Create and save a new file called error404.html, with contents as follows:
    <p>This is a custom 404 error page!</p>

17) Rename the copy of the wps.ear file in the /tmp directory that was previously exported to wps.bak.

18) Use the EARExpander.(bat|sh) utility to collapse the changes made back into a new wps.ear file. See the references section for the exact command to run based on your version of Portal.

19) Use the command to install the wps.ear file. e.g.
./ -user wpsadmin -password wpsadmin -c '$AdminApp install /tmp/wps.ear {-update -appname wps -deployejb -deployejb.classpath /usr/IBM/WebSphere/PortalServer/base/wp.base/shared/app/wp.base.jar}'

See the references section for the exact command to run based on your version of Portal.

20) Restart the Portal server.

21) Close the web browser. Open the web browser again. Attempt to access a nonexistent resource via a direct link to the Portal server, e.g: http://portalserver:10040/wps/noimage.jpg

Technical note #1: This modification will only affect resources directly under the /wps/ context. For resources (such as images, URLs, etc.) under the /wps/portal or /wps/myportal contexts, these are handled differently by Portal. Please see the technote Portal 6.1: HowTo redirect to a specific homepage when HTTP 404 Not Found encountered for more information on how to configure HTTP 404 Not Found error messages in such cases.

Technical note #2: Applications under the /wps context, such as /wps/myapplication, and their corresponding resources (e.g. /wps/myapplication/noimage.jpg), will not be affected by the web.xml modification in the wps.ear application. A similar change is required for each application's web.xml file to redirect to a specific custom 404 error page.

Technical note #3: Portal 6.1 does not correctly throw an HTTP 404 Not Found error in all cases. A code fix, available via PK87773 , will allow the HTTP 404 code to be correctly thrown.

Technical note #4: The custom 404 error page is not limited to HTML. A JSP page can be introduced that will utilize additional custom logic specific to the environment it is implemented in. As an example, "If a user encounters this error page, display a message for 5 seconds and then automatically redirect to a specific homepage". Such customization specifics is beyond the scope of this specific Technote.

Internal Use Only

Knowledge gained indirectly through PMR 83068,379,000. Issue in that PMR was not specific to this Technote, but, environment recreate by L2 lended insight for creation of this technote.

[{"Product":{"code":"SSHRKX","label":"WebSphere Portal"},"Business Unit":{"code":"BU012","label":"WCE"},"Component":"Installation & Configuration","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF012","label":"IBM i"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"}],"Version":"8.5;8.0","Edition":"Enable;Extend;Server;Express"},{"Product":{"code":"SS8KYD","label":"WebSphere Portal End of Support Products"},"Business Unit":{"code":"BU012","label":"WCE"},"Component":" ","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF012","label":"IBM i"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"}],"Version":"7.0;6.1","Edition":""}]

Document Information

Modified date:
27 August 2018