What you need and want to know about errors

I think it's fair to say that a user should never have to see an error whilst they surf your site. Such wishful-thinking is far from reality, as we all know. All we can do is try and make it a little less confusing for them. After all, what could be worse than them having to come across the good old 404 page.


This doesn't need to look like this of course. We all know that, using the reserved form name of "$$ReturnGeneralError" we can create a form that can display the error in any format we desire. Adding to this form a field called "MessageString" we can even show this exact message to them. Still this is not perfect. Your users don't really want to have to read that there has been an "Incorrect data type for operator @Function", do they? What you want to do is let them know that things aren't going well, while at the same time, remaining from alarming them with techno-speak.

How do we do this:

So the first thing we do is create the $$ReturnGeneralError form and try and make as much like the rest of the site as possible. We want them to know there has been an error but without startling them at the same time. Maybe some subtle red text as the error message.

What can we do now? One idea is to show an alternate message that makes the error make more sense. This was an idea that was suggested to me quite a while ago. Something I have to admit I had forgotten about until a few days ago when Steve Cannon of Numedia mailed me a copy of such a database that he had created himself. This article is about how I've taken said database and tarted it up a little with a few of my own ideas that should make a great example of user-friendly error-reporing.

Step 1:

Instead of Domino's own errors, why not provide an alternate version in "English". Using the list I started to compile so many moons ago we can provide this alternative.

Steve has done this by creating a form and a view to store a list of alternatives to the error messages. The form is called "Error Configuration" and is used to store the Domino error message and its English translation. The view is called, surpise surprise, "Error Configurations" and is used as a lookup. Using Domino's own message as the key, we can do a lookup from our error-form and display the alternative instead.

The attached database has this form and view in it for your convenience. Aren't we good to you!? It also already has a set of documents in it that list the most common errors likely to occur. Personally I would create this list in a database called "errors.nsf" in the root. We can then rely on a centrally updated list rather than have to maintain it in several places.

On our new $$ReturnGeneralError form add two fields, one called MessageString and one called AltMessageString. In the AltMessageString field place the following formula:

msg := @DbLookup( "Notes" : "NoCache"; "" : "errors.nsf"; "LU_ERRCONFIG"; MessageString; 2 );
chkMsg := @If( @IsError( msg ); "No help found for this error"; msg );

This will display something that means a little more that than what Domino tells us. An example is shown below:


This makes a little more sense doesn't it. Now we need to decide whether to show these errors at all and whom to. Most users need not know any specifics of an error. All they really need is to be told that all is not well. How about we only show the details of the error when we are in "debug" mode. Let's assume that you have Designer access if you are developing it. In this case we can hide the error details using a small @Formula. In the database I have added a field called "ShowHelp" and in it this formula:

@If( @TextToNumber( @Subset( @UserAccess( @DbName ); 1) ) > 5; 1; 0 )

We can then have a hide-when formula on the error section that is simple !ShowHelp.

Step 2:

Having developed and tested the application as best you can, the user will then start to use it. More than likely they are going to see an error sooner or later. What should happen then? We should know about it, as the developers, as well. Because the $$ReturnGeneralError is a "special" type of form we can't automate this with a WebQueryOpen agent so we need to rely on the user to let us know instead. Easiest way to do this is to give them either a number to call or a contact address to e-mail. In the case of the e-mail we can even help them out a little with a link that helps build their message. Here is the formula for the link:

"<a href=\"mailto: webmaster@yourdomain.com?subject=An error occurred whilst I was browsing the intranet&Body=The error read:" + MessageString + "%0D%0DWhen I looked at this page: " + Path_Info + "%0D%0DUsing this browser: " + HTTP_User_Agent + ".\">Intranet Support Team</a>"

The email will then look something like:


All we need to do then is rely on their good nature to press the Send button. Maybe you could organise for a competition, whereby the user to report the most errors wins a nice prize?

So, there you go:

Download the database and hopefully after you've played with it for a while you'll have some ideas of your own as to how to improve your own methods of dealing with errors. You'll need to place it on a server as local databases return your access level incorrectly.

Thanks again for Steve Cannon for putting the time in to the initial idea for the Error Messages database.


  1. Good idea

    Excellent idea.

    You might want to modify the example database as it is advisable to mark the following design elements as "Available to Public Access Users" $$ReturnAuthenticationFailure $$ReturnAuthorizationFailure $$ReturnGeneralError

    Just need a way of logging error messages automatically. Pity WebQueryOpenagent does not work.


    1. Re: Good idea

      Well, auto-logging would be nice. Could javascript do this via the onload-event of the form ?

      I could imagine that it can call a public agent with some &-Params. A document.submit is not the answer since the error form is opened in read mode.

      Some params could be: window.location.href (the page were the error occured) etc.

      onload: window.location.href = "/mylog.nsf/LogThisError?OpenAgent&Location=http://domain.com/db.nsf/view?OpenVi ew&Start=2&User=Denis%20Kopprasch&Browser=....."

      I didn't try this yet but i can imagine this could work. The agent could do the part of printing the "friendly" error message. To avoid duplicate posts of the same error (when the user presses the back-button), a computed for display UNID can be passed as an additional parameter too.

      Show the rest of this thread

  2. How to display message string and status code?

    Is this just too easy (and it's me who is stupid)?

    I don't find a hint anywhere to how you can have both, the original HTTP status code AND the MessageString displayed in your $$ReturnGeneralError form. Any idea how to do that?

    Also, does anybody know if the error messages are localized? Most companies do use the international english release, of course, but some may just not...

    1. Re: How to display message string and status code?

      I can say that those error strings are localized. e.g. "HTTP Web Server: Ausnahme: Unzulässige Argumente" in german (exception: invalid arguments).

      Therefore, the error code would be much more useful.

      By the way - did anyone try to assign custom error forms via domcfg.nsf yet ? I tried but it doesn't work like i excpected (e.g. for directory browsing).

      Show the rest of this thread

  3. Notes Mail Program by default


    This is a great article indeed. Well done to you and all these guys for supplying supports and solutions.

    Seems like the "mailto" functionality only works when you have "outlook express" (or similar) as your default email program. Thus clicking the "Intranet Support Team" mailto" link will fire up default email program set for the browser.

    However, having Notes Client as your default browser email program will suppress the functionality.

    Clicking the link will just open up notes client but not the "New Memo" page.

    Anyone tried this yet? Just that some clients out there have Notes Client as their email program by default.

    Regards, Mario

    1. Re: Notes Mail Program by default

      I'm having the same issue with the Notes client and long mailto links.

      I found this post in the R4/R5 dicussion forum on the Notes.net site -

      http://www-10.lotus.com/ldd/46dom.nsf/55c38d716d632d9b8525689b005ba1c0/b486b33d2 928a3a585256bad00412c20?OpenDocument&Highlight=0,mailto,web

    • avatar
    • TVL
    • Wed 13 Aug 2003

    Automatically mail error messages

    "Because the $$ReturnGeneralError is a "special" type of form we can't automate this with a WebQueryOpen agent so we need to rely on the user to let us know instead."

    There is a work around to this problem [no credit to me].

    Add a Computed for display field to this form. Make sure the text colour is the same as the background to 'hide' it from your users. Add the @MailSend formula with whatever parameters you want as the value. And Hey presto! everytime this form is created the details get e-mailed to you.

      • avatar
      • Jake
      • Wed 13 Aug 2003

      Re: Automatically mail error messages

      Thanks for that TVL. Was the credit not mine in the first place? I'm sure I've mentioned this before...

      There's no need to make it the same colour as the text. Just hide it.


  4. Static HTML & errors

    Hello, thanks for the info here, however I am still a little unsure how to use the information. I use the domino server on 5.010 & 4.6 to server static html, but I am unsure how to use the form based example. Do I put it somewhere the server can see it, but surely I need to tell the server to use the contents if it encounters an error.

    Regards, Andrew

  5. Error 500 HTTP Web Server: Invalid POST Request Ex

    We have an on-line job application where we want applicants to upload attachments, however we want to limit them to a sum of 1MB. The server document has been set for this to work properly. Problem: when an applicant exceeds that limit, we can't seem to trap the Error 500 HTTP Web Server: Invalid POST Request Exception, and replace it with a more user friendly message. Is there some reason why this does not work? Any help would be much appreciated.

      • avatar
      • Jake Howlett
      • Wed 2 Mar 2005

      Re: Error 500 HTTP Web Server: Invalid POST Reques

      Nancy. Have you seen this article - [<a href="unid/EPSD-5NMLXD?OpenDocument">Controlling the Size of Uploaded Files</a>]? Should help.


      Show the rest of this thread

  6. Is there any way of trapping other 404 errors?

    We have a website that relies on trapping ordinary HTTP errors and converting them into domino calls. This is a method of caching. In Domino 5 this is great but in 6 and 7 there seems to be no way of doing this.

    What do Domino 6 users do with basic 404 error messages as you do not seem to be able to customise them.

    ie http://www.codestore.net/store

    generates a bog standard IE 404 page which is not what you want.

    Thoughts and ideas please - this seems to me to be a major omission by Lotus.

      • avatar
      • Jake Howlett
      • Tue 3 May 2005

      Re: Is there any way of trapping other 404 errors?

      Hi Rupert,

      I didn't know there was any way of doing this, even in Domino 5.

      How did you get it working in R5?


      Show the rest of this thread

Your Comments


Navigate other articles in the category "Forms"

« Previous Article Next Article »
Further Control of Printing   Creating In-line Response Documents

About This Article

Author: Jake Howlett
Category: Forms
Hat Tip: Steve Cannon of Numedia
Keywords: Error; Message;


errors.zip (47 Kbytes)


Print Friendly

Let's Get Social

About This Website

CodeStore is all about web development. Concentrating on Lotus Domino, ASP.NET, Flex, SharePoint and all things internet.

Your host is Jake Howlett who runs his own web development company called Rockall Design and is always on the lookout for new and interesting work to do.

You can find me on Twitter and on Linked In.

Read more about this site »