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.

      Hide the rest of this thread

      1. Re: Good idea

        Relating to my previous post I forgot to mention:

        If the described idea works, there is a potential problem caused by a loop.

        This could be the case if errors occour for some reason while logging the original error via the agent. Therefore it is important to filter out those errors because this could end in loop, since the $$ReturnGeneralError-Form would be raised as well.

        1. Been there, just done that

          Just finished a db to log those error message.

          Used a meta tag refresh on $$ReturnGeneralError passing Path_Info and MessageString in the url to new page which displays the error message and run a QueryOpenAgent to save error document with some additional info like browser type, server name, CGI vars.

          I had forgotten I had used this method on another project 2 years ago!

          Just writing some error monitoring to email people when specific error occurs. Just like the Statitistics and event monitoring.

          1. Re: Been there, just done that

            Or you could get $$ReturnGeneralError to create a popup which grabs the fields from $$ReturnGeneralError and submits an error document then disappears.

            The popup could say:

            "This error is now being logged please wait..."

            as it may take some time to create the error document

            Have the page expire so people cannot refresh the page and submit the same error.

            No messy agents with long urls and no breaking the back button problems. Simple.

            1. Simpler alternative?

              Couldn't you just put a computed-for-display text field on the error form, that runs an @mailsend formula?

              This can either send to the developer or to a mail-in-database. I had a bash and am pretty happy with the results; here's an example:

              Add a field called "ErrorSummary" at the bottom of your error form, (text/comp-for-display only) with formula:

              "Request: " + @If(HTTPS="ON";"https://";"http://")+server_name+Path_Info+@NewLine+ "Referer: "+HTTP_Referer+@NewLine+ "Browser: "+HTTP_User_Agent+@NewLine+ "Query_String: "+Query_String_Decoded+@NewLine+ "Host: "+Remote_Host+@NewLine+ "IP: "+Remote_Addr

              (Make sure the CGI variables quoted have matching fields already)

              Then add your mailsend field with this formula:

              @MailSend("HTTPErrorLog";"";"";MessageString;"Details below:";"ClientSummary")

              Maybe I'm missing something - it's too simple!!


              1. GENIUS!

                If there's one thing I've learnt it's that a solution can never be [<i>too</i>] simple.. especially if it works so elegantly.

                Cheers Pat. I owe you a beer next time I make it to the North-West. Thanks for sharing it with us all.

                Obviously I tested this before congratulating you and in doing so found a "typo" in your formula for the field to send the mail. Hey, who's perfect?

                Should read: [<span class="formula">] @MailSend("HTTPErrorLog";"";"";MessageString;"Details below:"; ErrorSummary) [</span>] Instead of: [<span class="formula">] @MailSend("HTTPErrorLog";"";"";MessageString;"Details below:"; "ClientSummary") [</span>] I also found out what happens when you cause an error on an error form and that, for some reason, Domino on IIS don't like this.. ?

                Jake -codestore

                1. This is great, but... Re: GENIUS!

                  Alright, I put all this together and it works nicely, but I'm wondering: it seems odd to give the text explanation for the error in the web page for the user to see, and not include it in the email message for administrators and developers to see. My understanding of the original list of error messages was so that *we* could more easily diagnose problems with our systems.

                  For mine, I've changed it to send me the textual explanation of the error message, and I plan to remove this from what the regular user sees. (I also changed the first argument of @MailSend to be my e-mail address, since I don't know what that HTTPErrorLog is and wouldn't likely check it if I did.)

                  actually, if I'm more ambitious, I'll add a "UserExplanation" to the error configuration documents, and a "DeveloperExplanation" field to them as well, and show the "UserExplanation" field to the... well, you get the idea.

                  This really is ingenius. Now (if I use this everywhere) I'll never have to wonder: "are there errors that I don't know about?", nor should I wonder "what in tarnation's causing this &$^%@ Error 500!?"

                  This reply is already 8 levels deep and so replying at this level is disabled.

                  1. Re: This is great, but... Re: GENIUS!

                    I agree. The user shouldn't really see the text explanation. The idea behind it was that it was only visible in debug mode for the developer when they were designing the app. Ideally the end-user shouldn't have to see *any* errors message of any kind. Although they should of course be aware that all is not well.

                    The "HTTPErrorLog" mail address is, i guess, a Mail-In Database.

                    How you use it and who you send it to is naturally your choice. The idea behind it is what we should all understand.

                    You could go as far as having a field like this on certain pages where you wanted to know exactly who was reading them and when.

                    Jake -codestore

                • avatar
                • Jake Howlett
                • Thu 14 Mar 2002

                Worth noting..

                As I mentioned in the previous response the IIS/Domino combination doesn't seem to like this.

                This may be why:

                [<a href="http://www-1.ibm.com/support/manager.wss?rs=1&rt=0&org=sims&doc=E9DDF1B9B8 5889188625676F007BA480">Using Microsoft IIS as Domino R5 Server HTTP Stack Prevents @MailSend From Working</a>]

                D'oh! Why is nothing ever that simple ...

                Jake -codestore

                • avatar
                • N Wharton
                • Tue 26 Mar 2002

                Re: Simpler alternative?

                My(R5.06a designer) help file lists "@mailsend" under:

                "Domino @functions that are not supported on the Web "

                Very typical, alas : )

                • avatar
                • Peter von Stöckel
                • Sun 18 Jan 2004

                Another alternative?

                I know this conversation took place some time ago, but anyway...

                I added another form to my db and called it GeneralError. On the form $$ReturnGeneralError i put a meta refresh tag in the HTML head, and made the refresh URL point to the new GeneralError form.

                <meta http-equiv="refresh" content="0; url=http://servername/directory/database.nsf/GeneralError?ReadForm&URL=[Path_Inf o]&Ref=[HTTP_Referer]&Msg=[MessageString]">

                Parts in brackets are of course substituted with fields on the $$ReturnGeneralError form.

                This will give me an automated redirect to the GeneralError form, which does not have the same limitations as the $$ReturnGeneralError form. I just put the needed fields on the $$ReturnGeneralError and GeneralError forms. Massage the Query_String_Decoded into fields corresponding to the parameters in the GeneralError form, and have it all taken care of by a WebQueryOpen agent that can do anything I want.

                To be on the safe side I also put a link on the $$ReturnGeneralError form in case the web user is not redirected automatically.

                /Peter http://thor.pyttemjuk.nu/

          2. Re: Been there, just done that

            Hmm, why didn't I think of that...

            How do you fancy adding this functionality to the db I shared on the main document and we can share it with everybody else?

            Mail it over if you want to, Jake

            1. Re: Been there, just done that


              I have actually decided to use a hidden IFRAME in the $$ReturnGeneralError form which submits the error log document. That way annoying popups ar not needed. I have used a class to create the document, which also saves all CGI field values, so you don't need to be an author to create the document. If an error occurs that is not listed in the help it is automatically added to the help list.

              I have also added an error monitor that checks the log for particular errors and e-mails selected people. Although I have not tested it fully yet.

              I have not got round to modifying the other $$ forms yet. Although it would probably take just a few minutes. As I have to write a business plan for a Domino.Doc v2.5a to v3.1 migration.

              Any ideas on how to stop the error being re-submitted would be useful. Currently in my implementation if you refresh the page the error would be re-submitted and logged.

              I will send you what I have done so far you might find it useful. If you want me to finish it off left me know.

              Regards John Z Marshall - (Example DB in the post)

              1. Re: Been there, just done that

                To avoid resubmitting the error form when the user presses the reload button on that form, the agent that triggers in the webqueryopen of your iframe-form should handle this. It could check the last 1 or 2 errors that have been logged. Since the querystring would be the same, the agent could decide either to write a new error log document or not by comparing it to previous posts.

                Btw... i have an error form that dows not display if i try to open an unknow view for example. If i try to open an existing view with an invalid command (?OpenXXXX), the error-form is displayed. Are 404-errors handled some other way ?

                Cheers, Denis

                1. Can you use HTTP_Referer to not re-log on refresh?

                  I'm not sure whether this could work (sorry if it sounds way too beginner-ish, I'm a sys admin :-) , but one could try putting that if the page's HTTP_Referer entry is the same as the page itself (I'm not sure if "Refresh" on the browser changes the "HTTP_Refresh" variable), then the page should not be logged...

                  Hope this works,


                  This reply is already 8 levels deep and so replying at this level is disabled.

  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 »