If something goes wrong

When you build a software system, something can go wrong. You have to plan for that. It can be a programming error, an operator error, or a situation you haven’t planned for. I’m pretty sure you have seen web pages giving you cryptic error messages, thus indicating that something went wrong. In many cases, the given error message is useful for a programmer, but seldom for the average web user.

Fatal error:
Call to undefined function: some_function() in
on line 42

As a web user, what does this error message tell you? Maybe you can understand it. But can you do something about it? You can’t fix it, you’re left alone on finding your way out, it’s not helping you. Why then show it to you at all? The reason is, it wasn’t intended for you to see it. This error message is only useful for the developer. But he hasn’t planned for exactly this type of situation. Okay, it’s a programming error. But that you have to see this error in a form like this is lack of planning for this type of situation. Everybody knows or can understand that it’s not a good idea to have a web user look at a web page indicating an error like the one I showed you. But it’s still what happens in many cases. Why? Is it laziness on behalf of the developers, lack of good test cases, lack of imagination, lack of time or budget, or not enough knowledge? I think it’s a little of everything. The book Defensive Design for the Web from 37signals might tell you nothing a web developer should know already, but it contains a nice check list at the end to make sure he doesn’t forget to apply his knowledge.

To assist the developer in handling all not handled situations, synformation provides the mechanism of an error page that is called via forward() whenever a not handled error occurs. This error page is a normal synformation page with one exception: within the logic of the error page, you have access to an error object that holds all the information about the error. If you don’t define an error page within synformation, you’ll get something like the cryptic error shown above. It’s worse actually, because it might contain a Java stack trace because synformation runs on the Java platform.

I can only think of one reason to display a technical error message within the web page: the page is produced for the developer or tester. In all other cases, the user should see something more friendly, something that gives him some information on what to do next. He should not leave our web site in frustration. That’s why a typical synformation error page should contain logic like this:

$variable = getVariable("error");
if (null != $variable) {
    $msg = $error.toString();
    print S("X-ERROR-ERRORPAGE");
    // There's no need to send an email when an ACU can see the error
    if (isDevelopment() || getCurrentUser().isMemberOf("ACU")) {
<div id="infobox" class="infobox-info">
<h1><%%= R("ERROR-PAGE-HEADING") %></h1>
<p><%%= $msg %></p>
    } else {
        print S("X-INFO-WHAT-NEXT");
        sendMail(R("ADDRESS"), R("SUBJECT"), R("TEXT") + $msg);
} else {
    print S("PAGE-NOT-CALLABLE");

I will explain this code snippet. First, we have to find out if an error object actually exists. If it does, the users gets a friendly hint in his language that an unexpected error has occurred and we’re really sorry about that. If we are in development mode, or the user has logged in and he is a developer, the actual error message is displayed, too. If we have a normal web user, a text with options on what to do next is presented. An email is then sent off to the development team with all the technical information needed to reproduce and fix the error. In case no error object exists, this page was called without having an error. Maybe somebody typed in the URL in his browser. We tell him in friendly language, that this page is not intended to be used like that. We can also display some information on what to do next – he is already on our page, so why not keep him.

We all know that things can go wrong. But we should all care more for having an actual plan installed, if that happens. I’m not perfect in this regard either, so this post might help me as a reminder.

0 comments… add one

Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.