Make Better Error Messages

The other day I was trying to install mongodb on my Ubuntu computer. I followed the instructions, ran the sudo apt-get install command. Everything went smoothly, but then I tried to boot it up and was confronted with this nasty error.

posts/make-better-error-messages/mongod-error.png

After looking through this wall of text, I found this is the line that matters.

Unable to create/open lock file: /data/db/mongod.lock

Ok, simple enough, I need to create those directories. But that's not good enough, after some searching, it also has to belong to the special mongo group. No problem, did that and tried again but this time got the same error message.

What the heck mongodb? At this point I have no idea what's wrong, you supply no help and I'm forced to search random snippets of this error message to try and make sense of what went wrong.

After searching the internet for some magic solution. I never found one and decided to use something else. Very frustrating.

It Gets Worse

But that's not the worst I've seen. The worst error messages I have ever seen were Angularjs errors. Nothing is more cryptic, out of context and useless than Angulars.

posts/make-better-error-messages/angularjs-error.png Yes, Angular expects you to understand this mess

The first line is perfect.

Expected 60.0 to be a number

But everything after that is totally useless. In which file did this happen in? I don't know, it doesn't say. Do I get a line number? Nope. Can I at least have a stack trace so I can wind back the series of events? Nope. Which variable did this happen on? Don't know.

I like Angular, but the worst part of it is debugging it. I now judge libraries, frameworks and whatever else by the sophistication of the debug tools. Developers spend over half their time debugging, so make it the least painful please.

How Errors Messages Should Be

I don't like complaining without offering some solution. This is what an error message should include:

  • Detailed message of what went wrong, with what was given and what was expected
  • Stacktrace, with file paths, line number and column number
  • Some sort of option to start debugging on an error
  • Advice on how to solve the problem

Now all of these are not applicable to every type of error but supplying context is critical.

The last point is a huge bonus. If your application can detect what went wrong and tells you exactly how to solve the issue, you just wrote the perfect error message.

Example of A Perfect Error Message

This is the awd-sdk-v1 gem. When trying to use the gem without credentials you get this error.

posts/make-better-error-messages/aws-gem-error.png

This is the perfect error message, tells me the problem and gives me plenty of directions on how to solve it. No more searching or guessing on the users end.

Now of course it would be unreasonable to expect every error message to be like this, but for the most common errors I expect this. I'm looking at you mongodb.