Reading the error message carefully can help you see how the computer misinterpreted what you typed


The details have been changed since they aren't important but the lesson is the same.

A customer had the following problem with a command-line tool:

I've created a taglist but I can't seem to get it to work with the track command. When I ask it to track the taglist, it can't find it. But if I ask for all my taglists, there it is.

C:\> show taglists
You have 2 taglists:
 active (8 tags)
 closed (6 tags)

C:\> track active
No such tag "active".

Yes, the track command isn't working, but let's take a closer look at that error message. It says no such tag. Strange, because you are trying to track a taglist, not a tag. Shouldn't the error message be no such taglist?

Aha, the problem is that the track command takes a list of tags on the command line, not a taglist name. The error message is correct: There is no such tag called active. Because active isn't a tag name; it's a taglist name.

C:\> track -taglist active
Taglist "active" is now being tracked.

Today's lesson: Look carefully at what the error message complaining about; it may not be what you expect.

Exercise: Diagnose the following error message, given no information about the program being used beyond what is presented here:

I accidentally made a change (transaction number 12345) to the file XYZ, and I want to back it out. But when I run the backout command, I get an error. Can somebody help me?

C:\> backout 12345
12345 - file not found
Comments (17)
  1. Steve Syfuhs says:

    Same issue.  The command isn’t being called correctly.  It should be

    backout XYZ 12345

    Or more precisely, whatever the documentation has defined as the correct calling parameters — if the docs exist anyway.

  2. Simón says:

    Easy.

    What the user typed in as a transaction number is being interpreted by the backout program as a filename, and connot find it.

    Always try to get a look at the documentaion, or the program’s help (using /?, –help, -h, whatever, try all possible ways!) before actually performing a task with a program for the first time; specially if that piece of software affects some important files or data.

  3. kingofgames999 says:

    perhaps the change he made to file XYZ was to rename or delete it, but didn’t mention that since it wouldn’t be important and computers are hard to use.

  4. Pierre B. says:

    I find this entry interesting from a program design point-of-view. The main design flaw is that different types of objects have separate namespaces. Compare this to programming languages: most don’t separate namespace by object types and those that do (for example keeping function names and variable names separate) often invite just this type of confusion and error.

    I think this shows that it’s a good design practice to keep a single namespace of all your objects and use the namespace itself to arbitratre between name clashes, by supporting, for example, hierachical names.

    Good design can get rid of whole classes of errors. (And exchange them for other classes of errors. :) )

  5. @Pierre: But once you start using hierarchical names, your names start getting really long (or really cryptic), making them painful to type out in full.

    You can solve this problem by introducing the notion of context (e.g. C++’s "using namespace foo", or a file system’s current working directory), but then you’re back where you began — separate namespaces with separate contexts.

  6. Adam V says:

    It could have been worse – if this person had a tag "active" within the taglist "active", they’d be saying "I made a taglist ‘active’, then tried to track it saying ‘track active’, and not everything is showing up." The command would be "working", in the sense of "not returning an error", but it would have been returning less than they expected, and they’d be clueless. At least in this case, the error message is all you need to read to fix the problem.

    (Even more fun, if the tag "active" were within the taglist "closed", they’d be yelling that they were getting "closed" items instead of "active" ones.)

  7. David Jones says:

    @Simón: You are assuming that a program invokved with invalid arguments or -help, etc. will actually display help.

    I have seen many examples where programs invoked with -help may actually do something destructive, especially in-house scripts developed at client sites.

    Invoking a program hoping to get help is dangerous, and more often than not, futile.

  8. njkayaker says:

    "I have seen many examples where programs invoked with -help may actually do something destructive, especially in-house scripts developed at client sites."

    You avoid all sorts of problems by sitting quietly with your hands folded.

  9. Dan says:

    First thing to try when a console command errors and you’re not sure why:

    Append /?, -? –help, or ? to the command line and read carefully.

  10. Dan says:

    Oops, beaten to the punch.

    Anyways, if a program requires some sort of parameter to do anything useful, it’s usually OK to pass it nothing or –help (or variants) since it can’t do anything unless finds a needed parameter, even if it doesn’t understand the parameters passed.

    And of course you’re going to want to be more careful with scripts than with third-party professional, polished apps which are less likely to let you do destructive things by accident…

  11. Guillaume says:

    I would type this command :

     where backout

    There could be a program with the same name that comes up first in the path search. It could be an older version, for example. That other program has a different command line, and probably a different purpose.

    It used to happen to me, confusing Windows "find" my win32 version of GNU’s find.

  12. Anonymous Coward says:

    @David: like removing the object tree named "help" – which is where all documentation resides.

  13. Me says:

    This clearly illustrates how programmers are not literate enough and cannot put together a sentence which clearly explains the error condition without the need to stare at the message for several minutes trying to decipher it.

  14. ~JW~ says:

    Hmmmm…

    ‘Subsribe to Raymond’s blog by email’ takes me to http://blogs.msdn.com/Msgs/default.aspx?MessageID=17. Enter email and password: "The username and/or password cannot be validated, or your account is locked out or has not been approved yet."

    Gee, I must have forgotten my email after all this time. What the hell, sign up for a new one: Click Join: "500 – Internal server error.

    There is a problem with the resource you are looking for, and it cannot be displayed."

    I must have clicked with the wrong finger.

  15. Drak says:

    @Me: or it illustrates that users cannot and will not read error message.

  16. rw says:

    Isn’t that a typical case of customer outsourcing the process of thinking to support? I often experience that support emails drop down dramatically during my vacation (beginning with the first auto-reply) and boost up as soon as I’m back. Hard to believe that problems get less when I’m not in the office, so I assume that because of the auto-reply mail, people finally start thinking themselves and actually are able to sind the right solution without help.

  17. Phydaux says:

    The best UI design in the world won’t change this human behaviour. If there is a problem, a user will throw their hands up in the air and give-up. "It’s not working"

    It doesn’t really matter how well you try and hold the hands of users there will always be those who refuse to stop and think about what has gone wrong. They need to get their work done, their tool is broken so they go to the people who fix IT problems. Even if it’s completely within their capabilities. This means they won’t even read the error message, even if the error message tells them exactly what is wrong (and sometimes) how it can be fixed.

    I work in a finance company developing internal tools for other techy people and some for the admin guys. I have learnt to stop complaining about "stupid" users and just accept that troubleshooting/problem solving isn’t what they are good at, and isn’t even necessary for many of them.

Comments are closed.