First, try reading the error message, episode 3: Even programmers see error messages without reading them

As we all know, users don't read error messages. And, sad to say, this behavior extends to the group of people you would think pay the most attention to error messages, namely, programmers, who are the people who cause your computer to display the error messages!

Today's example comes from an internal programmer's tool which I will call Program Q.

I'm trying to back out an update I made to record 19 of our table (which was entered as transaction 512), but I can't get it to work:

C:\> q backout 512
Transaction opened for record 19 - must reconcile backout

C:\> q commit all
Transaction 520 created for 1 record
Committing transaction 520
Record 19 - must reconcile backout
Unreconciled changes pending - use 'q reconcile' to resolve
Commit failed -- fix problems above and then use 'q commit 520'

What is the problem here, and how do I fix it?

The transaction couldn't be backed out because somebody else made a change to record 19 since your original erroneous update, and the system wants you to reconcile this conflict.

But that's beside the point. The point is that the user here merely saw that there was an error and didn't actually read any of the error messages. There were four error messages, and every single one told him what he needed to do!

C:\> q backout 512
Transaction opened for record 19 - must reconcile backout

C:\> q commit all
Transaction 520 created for 1 record
Committing transaction 520
Record 19 - must reconcile backout
Unreconciled changes pending - use 'q reconcile' to resolve
Commit failed -- fix problems above and then use 'q commit 520'
Comments (37)
  1. Random832 says:

    Maybe he didn’t understand something (e.g. what "unreconciled" means – "conflicting changes" and maybe a pointer to the other transaction where the other changes were actually made would have been clearer) and knew better than to blindly follow instructions included in an error message without understanding what’s going on.

  2. D. Garlans says:

    Random: Ah, but then the programmer should have asked "I can see that there’s a problem with reconciliation, but I don’t understand what could have caused that."

    At least then it becomes a training issue, rather than a "I’m completely oblivious to everything" problem.

  3. Alexandre B. says:

    Like D. Garlans said, if the problem was lack of understanding, it would be entirely justified. However, the message told him more or less exactly what he needed to do, namely "use ‘q reconcile’ to resolve"

  4. John says:

    What really annoys me is that some of my fellow programmers don’t have some of the most common Win32 error codes memorized.  5 = ACCESS_DENIED, 2 = FILE_NOT_FOUND, etc.  These come up ALL THE TIME and they still have to look them up.  I mean seriously, if you see something this often you think you would just naturally memorize it at some point.  I understand this is somewhat esoteric, but Win32 programmers must encounter these error codes multiple times every day, right?  How can you not know these by heart?

  5. blah says:

    Make a more helpful program and the universe will throw increasingly helpless losers at it.

  6. Marquess says:


    You might want to tell them about this new technology called “Post-Its.”

  7. dalek says:

    Are you allowed to react with RTFM (or in this case RTFEM) or is this against company policy?

  8. ReWrite says:


    The code I write doesn’t run into the error values often enough for me to know them by heart.  OTOH, I get peeved when people don’t know what U+FEFF or U+FFFD mean, that U+FFFE is invalid (and why) and how many bytes it takes to store U+10117 in UTF-8 and UTF-16.

  9. Dave says:

    While I completely agree with the general premise of this post, I also have difficulty with programs that dump out an error when it appears that the program itself knows how to deal with the problem (or at least what the next step should be).

    Given that we are already executing Q, and apparently the correct course of action is to type in “q reconcile”, why doesn’t it just do it (at least to the point of displaying the information).

    [There’s a reason why the operations are separated, in this case. -Raymond]
  10. Joshua says:

    Dave: command programs like these are probably intended for automation where unexpectedly executing reconcile will throw the script off (that input you are reading might be a stream intended for some later command in the script).

  11. M Hotchin says:

    @Dave – adding info like that makes the command harder to script.  Right now the output is both short and predictable – easily parsed.  The reconciliation output could be arbitrarily long.

    Of course, waiting for user input is also a no-no in this case (assuming ‘commit’ doesn’t normally block on the user).

  12. Boris says:

    Without knowing what q does and what a backout is:

    > Transaction opened for record 19 – must reconcile backout

    This is not obviously an instruction to the user. It might mean “I (the program) will now reconcile backout”. Some programs do give themselves instructions as a way to tell the user what the program is doing.

    > Unreconciled changes pending – use ‘q reconcile’ to resolve

    This might mean “Ureconciled changes pending. I will now use ‘q reconcile’ to resolve”

    > Commit failed — fix problems above and then use ‘q commit 520’

    Even this might be misinterpreted, but it is unlikely and obviously it was not.

    Granted, once this last line appears, I would most likely go back up and determine which of the lines of text above is most likely to be mentioning a “problem”, but I can see the potential for not immediately seeing why there’s an error.

    [Don’t waste time with a detailed textual analysis – I just made up those messages myself. They aren’t the actual error messages. (Besides, the manual for the Q program goes into more detail on the backout process.) -Raymond]
  13. acq says:

    Just like boris, I interpreted the message "blabla — must do something" as a "talky program explains what the mentioned program must to do, not what I have to do." One "you" is missing there, or "must" is too much: "reconcile backout first!"

    "Unreconciled changes pending" is also not the obvious wording unless you really know the semantics. "Pending"? Doesn’t say if the action successful or not? Maybe "pending" is something normal, exactly what should happen. But "use ‘q reconcile’ to resolve" is obviously a direction to the user, the first time something useful. So it’s probable that "Unreconciled changes pending" in fact meant "Unreconciled changes were not accepted".

    The last line is clearly understandable. But it refers to "problems before" which are at least a bit probelmatically stated.

  14. Peter says:

    “Don’t waste time with a detailed textual analysis – I just made up those messages myself.”

    You might have mentioned… ;)  “Must reconcile backout” is complete and utter jibberish to me.  Before reading your last comment, I had nothing but sympathy for the hapless user.

    [All customer questions are paraphrased, and all internal tools contain fake output. -Raymond]
  15. JapanMAn says:

    Programmers are users.

  16. Those who do not understand source code control systems are condemned to make life hell for the rest of us.

  17. Nick says:


    That’s going in my .sig

  18. Andrew Brehm says:

    Now this blog translates to bad German automatically when I access it. I don’t know why it would do this as nothing on my computer (Mac OS X, OmniWeb) is configured for German.

    I cannot read bad German. And I cannot switch it back to English.

    What is this?

  19. Mark T. Tomczak says:

    Given the context, I smell fear. Source control programs are notoriously finicky and full of hard-to-understand, nuanced behavior, and the penalty for making a mistake is deleted work—yours or someone else’s.

    I suspect that this user had been burned by failure to understand the options the program was presenting before, and seeing this unexpected error message, they were going to an experienced human for help. While they could probably understand the situation with a bit of thought, the penalty for mistakes may have been too high to try, in their opinion. What if the program ‘reconciles’ by throwing out the working copy?

    If I were to make one change to this UI, I’d add a ‘?’ option to get directly to the relevant section of the manual.

    It’s surprising to me how many otherwise competent and productive developers don’t think source control is something they should have to invest brain cycles to learn. In a case like this, I think "RTFM" is an acceptable answer, but a touch of empathy for the hours of productivity lost in the past would also be appreciated.

  20. recursive error says:

    The program should of course analyze *why* somebody else made a change to record 19 and display that to the user. Conflict resolution is not usually simple to solve automatically (in a good way), the program usually has to interact with the user to do the right thing.

    [That’s exactly what the “q reconcile” command does. It shows the changes that were made by you and the changes made by others and asks you to reconcile them. (Totally irrelevant to the point of the story, of course.) -Raymond]
  21. Jeremy Morton [MSFT] says:


    “If I were to make one change to this UI, I’d add a ‘?’ option to get directly to the relevant section of the manual.”

    The “q commit all” command isn’t interactive to accept any input, like a “?”.

    However, there is a “q help commit”, “q help backout” and “q help reconcile”, as well as “q commit -?”, etc. Interestingly enough, “q reconcile” is interactive and accepts an input of “?”.

    As a member of a team that makes a q program, I have been interested in better ways for the UI to communicate what must be done; it seems to me that Raymond’s view is that, after some point of clarity, it doesn’t matter as much, because the user hasn’t bothered reading it; as you say, there is probably some sort of aversion or fear involved there.

    My favourite is that we had long had an error message that basically said “no permission to thingamajig”.

    After several years of supporting the message and getting a lot of queries asking what could cause them to not have permission, I pushed for putting more information in to explain the common reasons and how to get in touch with the administrators for the specific q server instance that they are using. The message was changed to something like “no permission to thingamajig; see ‘q help permissions’.” and a help topic was written to explain the several common reasons for this state followed by something like “If the above seem to be correct, please contact your server’s admins at _____” with an admin defined mailto: or http: URL.

    After this was put into place, we still get asked about the error message; they almost always cut and paste the error message and ask what it means. [Incidentally, they are always positive that they do have permissions.] The first reply that I always do is to quote their error message:

    “no permission to thingamajig; see ‘q help permissions’.”

    Did you run ‘q help permissions’?

    Invariably, it’s the same answer:


  22. Chris R says:

    Come on guys. This is a standard situation in Subversion and possibly many other version control systems. If there are conflicting changes, the software tells you to go *review* and *merge* these changes.

    I am a bit bemused by this: Raymond tells a humorous story, the setup of which describes a common behaviour of some programming tools. But since a piece of *internal* software is mentioned as an example, everybody proceeds to pick the software apart and argue that its messages are too cryptic and that it should operate automatically etc. etc.

    I believe the program is doing what it’s gotta do, and as Raymond repeatedly mentions, it is beside the point anyway.

    Nice story, thanks.

  23. Nick says:

    What boggles my mind is when a fellow programmer (or a sysadmin) reads the error message but then their brain just shuts down.

    Them: Hey, I’m trying to modify the database and I’m getting a "Operation must use an updateable query" error. I’ve been working on this for an hour and can’t figure it out.  Do you have any ideas?

    Me: Did you Goog^H^H^H^HBing the error message?

    Them: No, why?

    Me, 5-10 seconds later: It probably means the permissions on the database are wrong.  Fix your ACLs.

    Them: Oh, wow, that works! Thanks!  How did you know that?!

    Me: *sigh*

    Even if the error message isn’t terribly helpful, search engines for the Internets have been around for a while.  Use them!

  24. Drak says:

    I can relate to the fear thing if this is about source control, but I generally go to someone I trust with source control and ask them ‘Is it OK to blindly follow the instruction the program is giving me or should I take some action first (like make a local backup, just in case).

    But never ‘huh? wut? error message?’

  25. prunoki says:

    The following is an example why you should not always do what the program tells you. All credits go to Joel Spolsky, this is an excerpt from his Mercury tutorial.

    C:Usersjoelrecipes> hg push

    pushing to

    searching for changes

    abort: push creates new remote heads!

    (did you forget to merge? use push -f to force)

    Ahhh!! Failure! By the way… that message you see there? The one that says use push -f to force? That’s terrible advice. Never, ever, EVER use push -f to force. You will regret it. Trust me for now.

  26. 104 says:

    prunoki: typical users might fall into the trap of interpreting that as "advice", but you as a dev should know that computers don’t give advice. red flags should be flapping like crazy if you blindly follow an instruction like that message without understanding WHY. devs tell computers what to do, not the other way around.

  27. kog999 says:

    I once had a program display the message "Press any key to continue" I searched for hours for the any key but it simply did not exist on my keyboard so the program just sat there forever.

  28. I suspect CYA could be at work here. If X does only what he’s trained to do, he can’t be blamed if something goes wrong.

    Even though the error tells X exactly what to do, it might not have been in the training. So instead, he escalates it and waits for someone else who can be pointed at and blamed if the reconcile goes wrong.

    ("Not my fault. I only did what the support man said to do.")

  29. kog999 says:

    I actually just had something kind of similar happen to me just now. I sometimes do helpdesk support for employees. Had someone call up saying website X is not working. This was an external website that we encourage our users to use but we do not directly support or control but I’d figure I would give it a shot.

    Me: what isn’t working; does the website not come up at all? Does your password not work? Does and error display?  

    User: I cannot login.

    Me: ok does it say the password is wrong?

    User: no I type in my password and it says I need to confirm my email address? But I don’t see my page

    Me: ok, what happens when you confirm you email address?

    User: I don’t know

    Me: Try typing in your email address and hitting ok (I hadn’t actually seen the page but my physic powers told me there would be a spot to type in an email address and an ok button)

    User: my page is there now Thank you.

  30. Maurits says:

    To be fair, Jeremy and Raymond aren’t in the best position to judge whether these error messages are being read.  They only hear about it when the messages are not read.  No-one sends them email to say "by the way, I ran ‘q reconcile’ like the error suggested and it solved my problem."

    It’s like working in a poison control center and saying "people sure have a hard time reading the instructions on paint thinner."

  31. Maurits says:

    I searched for hours for the any key

    I pressed Shift a million times but nothing happened.

  32. Pierre B. says:

    Jeremy Morton:

    What I’ve been doing lately is to always output three lines of error report:

    1. The error and its cause.
    2. How to fix it in plain English.

    3. The actual command to fix it.

    Usually in the form:

    Error: cannot do X because of Y.

    To be able to do X, you must first do Z.

    (Actual command that would do Z.)

    So q is really quite close, but the inital error might be too terse. Applying my method, I’d expect:

    C:> q backout 512

    Cannot backout 512 due to conflicts in record 19.

    You must reconcile the changes to record 19 in order to backout 512.

    Try the command: q reconcile

  33. Igor Levicki says:

    Error messages can be really cryptic, not to mention nowadays when people rely on .Net exception handling and instead of real error messages user only see .Net exceptions and stack traces.

  34. Falcon says:

    I agree that if the user has fears or concerns about unexpected consequences, they should state those when asking for help. Same if they feel the error message is unclear – if there’s to be any hope of addressing this problem, the authors of the program need to know about it.

  35. So was this a newbie?  Or a PM? :)

  36. Rob Kennedy says:

    Actually, “104,” the Mercurial guide says this: “If at any place any command complains, your best bet is to read what it tells you and follow that advice.”

    So there we have an explicit example of software giving advice to devs. (Only devs would use Mercurial, after all.) Spolsky advises ignoring the guide’s instructions, at least in the case of “hg push.”

    Too often we encounter error messages that don’t really tell us what the problem is. “The parameter is incorrect.” “PC Load Letter.” When that happens often enough, we form the idea that no error message tells us what the problem is, and so it’s not worth reading any at all. Instead, we should go find our local technical expert and ask for help.

    I think the only remedy for that is to continue to write good, accurate error messages. And not just trivially accurate (“an error occurred”), but accurate and useful to the people who are likely to encounter it in the wild.

    I try to explain to people that indeed sometimes error messages aren’t accurate. They indicate something is wrong, but they don’t correctly diagnose the problem. But only sometimes. Other times, an error message might really mean exactly what it says, and unless we have evidence that the message is wrong this time, we really need to give the computer the benefit of the doubt and assume the message is correct. (For instance, sometimes when the compiler says it expected a semicolon, it really means you’re missing a semicolon, no matter how many times another semicolon would just lead to more and worse syntax errors.)

    [I had no problem understanding “PC Load Letter”. It’s saying “Put in (load) letter (sized paper).” -Raymond]

Comments are closed.