Error messages are like poetry

Reading error messages are like reading poetry.

The message conveys an error has occurred. It is upto us, to read between the lines and interpret, where the error occured and why. This is not the case with all error messages but it is not uncommon to come across error messages that are poetic at best.

Example

Here is an example I encountered recently.

There is a REST API authenticated by an API key. There is a client that needs to invoke the REST API.
The client reads the key from AWS secret manager. The client tries to invoke the REST API and we see the error.

1
net/http: invalid header field value for \"X-Api-Key\""

Our first instict was to check the key on the client and servers. They seem to be correct.
We checked our server logs to see if the server was recording a 401 status. But we see no logs on the server as well.
We are now perplexed since the server is not recording the error.

We then search the error message. To give additional context, the client and the server both are golang applications.
The error message was found inside golang source code.
On inspecting further we found that there is code in the go net/http package that validates the headers on the client side.
This lead us to believe that an issue with the API key prevented the client from making a call to the server.

Finally we tried viewing the secret via command line rather than using the AWS UI.

1
aws secretsmanager get-secret-value --region us-east-1  --secret-id <secret-name>

And !! we could spot an additional newline character \n which was not showing up on the UI. Mystery solved !!

Schools, colleges and tutorials teach us how to learn a new technology or a programming language, but seldom are we taught the discipline to read error messages. I would also go on to say that seldom are we taught how to write meaningful error messages.

My immediate reaction on seeing error messages were panic and anxiety.
I used dread to see the error messages in “red”.

I think the first step is to accept that errors and failures are part and parcel of software development.
It is good to detect errors in the early stages of software development.

I recall listening to a Freakonomics podcast series, “How to succeed at failing”, where one of the strategies is to list all the possible factors that can cause a project to fail. Once all possible reasons have been listed then the next strategy is to build a plan that will account to mitigate all these and work towards making the project a success.

Well written errors

What is a well written error message ?

An error message that gives us an indicaton on

  1. Where the error has occurred
  2. Why the error has occurred
  3. What data cause the error

If an error message is well written, it is clear as to what needs to be corrected based on the context.

Well maintained open source projects will also have good documentation or a FAQ (Frequently Asked Questions) section that talk about these errors.

Poetic error messages

These are error messages where the error message might give very little clue on Where, What and Why an error occurred.

In such scenarios it is very important to have the right attitude and patience to try and resolve the error.

Over a period of time I have secretly started enjoying these scenarios as it feels like solving a puzzle.

Next course of action

When it is not easy to resolve an error message, here are somethings I do:

  1. Inspect source code.
    1. If the source code is accessible, the error message can be searched to understand which part of the code is returning the error message and in what context.
  2. Search the internet. Internet searches will mainly return
    1. Stackoverflow questions, where others have encountered the same error and have taken time to ask the question. There are other good samaritans who have taken the time to answer these questions benefiting the developer community.
    2. Blog Posts. There are other fellow developers who have encountered this issue and have found ways to solve the error or get around it. They document their findings on blog posts.
    3. Github issues. If the error is originating from an open source project, there is a high chance that the error message has been raised as an issue. A project that is well maintained would probably have addressed as to why this issue was caused.
    4. Reddit posts
    5. Community Forums Many open source projects have their own forums, slack or discord channels. These forums are generally welcoming and are open to questions and feedback.

Good developer citizens

There are scenarios where none of the above options help. We go down a rabbit hole trying to resolve questions or there is nothing available on the internet that is able to resolve the issue.

I see these as opportunities to be a good developer citizen.

One can do the following

  1. Ask the question on Stackoverflow if the question was not asked before ?
  2. Post the question on the project’s Github issues
  3. Post the question on the projects’s forum, slack or discord community.
  4. Last but not the least, if the error was resolved, take the time to write up a blog post to help others in future.

Going the extra mile

The main hurdle is to acknowlegde that sometimes these error messages are cryptic and can make one go down the rabbit hole.

We could do ourselves a favor by making sure we WRITE meaningful error messages. This will not only help others but will also help us in the future.