Intercept HTTP Errors in Domino

Configure custom error pages when a resource can not be found.

Reviewed December 2019 for HCL Domino 10. No changes, the configuration is upwards compatible from previous versions.

We get two different types of HTTP 404 Errors returned to the browser, the missing file or the database error.

Before we dig into the details, always keep in mind that the different browser handle errors differently. Not just between Chrome, Firefox, IE and others, a version upgrade may also handle them differently. With this in mind, we look at the Domino configuration to return our own custom message when an error occurs.

The HTTP 404 error message is a standard response when a database or a file was not found. The good thing is that the communication to the server works. Looking at the Domino URL, the 404 error refers to the path including design elements. All the green part is usually considered the file name, example:

This error can not be intercepted or redirected with two exceptions.
1. A system wide custom error page can be sent to the browser, but the HTTP 404 Error is still unchanged. This makes sense if you consider web crawlers (yahoo, google etc) that don't want to cache invalid URLs, they depend on the 404 error code.
2. You can also handle the 404 Error in a database by adding the $$ReturnGeneralError forms. Now it is up to the Developer how view and document errors are handled. At this time, I'm not diving any further into this option and concentrate on the system wide error page.

You can however customize the error page that is returned to the browser. It is a configuration option in the browser and may not always produce the expected result.

Example of error handling exception in IE
404 in IE Some versions of Microsoft Internet Explorer, the 404 error shows a help page that is generated by IE. This is NOT the message returned by the HTTP server or the custom error pages should one exist. IE ignores the custom page and shows it's own help page.

404 in IE configuration To disable the IE help page, you need to change the Advanced Options in IE as per picture to the right.
Goto > Tools > Internet Options
Open the Advanced Tab
Find Show friendly HTTP error messages
Uncheck the option.

404 in IE Now you will see the error that is returned from the HTTP server.

Domino Configuration for overwrite
error overwrite This standard error message can be overwritten on the Domino server.
I changed the error page to display the company logo and provide some help regarding the error. Keep in mind, the 404 Error Code is still returned to the browser, only the page looks different. To accomplish this, you need a file with the HTML code and a NOTES.INI setting that points to the file.

Create a file with the HTML code in it. This example uses a file with the nameerror.html
<title>HTTP 404 Page Not Found</title>
<style type="text/css">
body {font-size:10pt; font-family:sans-serif; background-color:#883366;}
em {font-size:12pt; font-family:sans-serif; font-weight:bold; font-style:italic; color:#c06020; }
A:link { font: bold 12px Arial,sans-serif; color: #0066CC; }
A:visited { font: bold 12px Arial,sans-serif; color: #0066CC; }
A:active { font: bold 12px Arial,sans-serif; color: #0066CC; }

<div align=center><table border="0" bgcolor="#d0d0d0"><tr valign="top"><td width="780">
<table border=0><TR><TD width="100" align=left>&nbsp;</td>
<td><font color="#000000"><b>Your Company</b></font></td></tr>
</table><table border=0 bgcolor="#FFFFFF"><tr><td width="100" align=left>&nbsp;</td>
<td width="680" align=left><br>
<em>The page you requested is not available.</em><br><br>
Try one of the following:
<li>If you typed the address, verify the correct spelling
<li>If you were referred to this page, go to the <a href="/">home page</a> and navigate to the page.

Error message The above HTML will produce a page like the one to the right. Change the colored text to suit your needs and include links to point to more support pages.

The NOTES.INI variable you need to add is:
Copy the error.html file into the Domino/html folder under the Domino data directory.
Note: If you already customized your Domino Web server, the html files may be in a different folder. Check the Web Site documents for the exact location. You could use different pages depending on the website.

Database/Path Configuration for overwrite
The Database Error 404 error message is configured in the domcfg.nsf. If the database doesn't already exist, create a new one called domcfg.nsf in the data directory (use all lowercase). The database must be created from the advance template Domino Web Server Configuration (domcfg5.ntf). The Domino Web Server Configuration database maps the Login, Password and Error Pages. Every configured website can have it's own, unique setup.

To create the error messages, map the individual error to a custom form. The different errors are:

  • General Errors
  • Authentication Failures
  • Authorization Failures
  • Password Expired Errors
  • Password Change Not Allowed Errors
  • Password Change Submitted Responses
  • Document Deleted Responses

    For this document here, the one I'm interested in is the General Errors. It is a bit confusing which error is triggered. The two examples here should shed some light on the mistery.

    For this document here, the one I'm interested in is the General Errors. It is a bit confusing which error is triggered. The two examples here should shed some light on the mistery.

    Example 1: will display the error as per configuration in the NOTES.INI
    Example 2: will display the error as per General Errors configuration in the domcfg.nsf
    Example 3: will display the error as per General Errors configuration in the domcfg.nsf
    When the URL looks like a Notes Database as per Example 2, then the domcfg.nsf page is returned.
    And when the database exists, but the view (or document) does not exist, then the same domcfg.nsf page as in #2 is returned.

    First published on October 23, 2010
    Last revised on December 04, 2019
    Contact Us  Help