Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Write better error messages

wix-ux.com

Post reply on HN
Print view View original

121–130 of 265 posts

Re: Write better error messages

#121

Post by eyelidlessness »

mariusmg wrote: post #17
zagrebian wrote: post #8

Earlier quoted context omitted.

This just means that the error message needs to be more clear. For example, after the error itself, it could give direct advice: “PERFORM THESE STEPS: You must define ENVVAR. Go to . Set ENVVAR to a proper value and restart the service.” Notice the direct language. It reads like an order. The less direct the message, the higher the chances that the user will not act upon it.

>it could give direct advice: “PERFORM THESE STEPS: You must define ENVVAR. Go to . Set ENVVAR to a proper value and restart the service.” Really, should logs also be documentation now ? Just mindlessly logging the same "advice" over and over again each time the error happen ?

This is fairly common in good error logs.

Re: Write better error messages

#122

Post by pwinnski »

mariusmg wrote: post #17
zagrebian wrote: post #8

Earlier quoted context omitted.

This just means that the error message needs to be more clear. For example, after the error itself, it could give direct advice: “PERFORM THESE STEPS: You must define ENVVAR. Go to . Set ENVVAR to a proper value and restart the service.” Notice the direct language. It reads like an order. The less direct the message, the higher the chances that the user will not act upon it.

>it could give direct advice: “PERFORM THESE STEPS: You must define ENVVAR. Go to . Set ENVVAR to a proper value and restart the service.” Really, should logs also be documentation now ? Just mindlessly logging the same "advice" over and over again each time the error happen ?

Yes!

There are people who don't read formal documentation but do read logs, after all.

If the advice is the same over and over again, then yes, give the advice over and over again. I wouldn't want to assume that someone has read every line of the logs, or has started to read top-to-bottom, so the advice should always be among the most recent lines in the log, and the only way to ensure that is to give the advice again each time the error happens.

Re: Write better error messages

#123

Post by pwinnski »

throw827474737 wrote: post #50
ddulaney wrote: post #32

Earlier quoted context omitted.

Logs can definitely be a form of documentation. I write software that is generally run low in the stack, quietly doing some mundane tasks that are business-critical but rarely thought about. If one of our clients has to mess with our software beyond the occasional update, that was a failing. Not all software is like this, but lots of it is -- its value is that no human needs to be involved. I need to write log messag…

If it is that simple, the why doesn't the code fix it itself? But no, usually there is 1/2/3 likely things, but it also could be anything else.. and that kind if unexpected errors even often have no default-fix. No, the most best thing is to point to the documentation which has that, and not printig out manpages of docs in error messages now. > I write software that is generally run low in the stack What stack, how l…

In the case at hand, where an environment variable isn't set, how exactly should the code fix itself? Human interaction is necessary, which is the reason the log message should spell out what the human needs to do.

If I'm starting a service and see a pointer in the logs to documentation, that seems like an incredibly broken approach to me. Why would I look at missing or out-of-date documentation that may or may not be at hand when the code that knows the problem is right there and can just tell me? A log message like you're describing might as well say, "Something went wrong, but I don't want to tell you what. Instead check page 43 of the document in the third file cabinet from the left in that room over there on your right. No, your other right."

Re: Write better error messages

#124

Post by bonoboTP »

hprotagonist wrote: post #3

I would, if i had any evidence at all that they would be read and acted on. I’m convinced even seemingly competent people are just rendered contextually blind by the appearance of any error at all. In the past month, i’ve had about a dozen interactions like this: developer: your service crashed, here’s a screenshot of the last 5 lines of the crash me: do you see where the final text you just pasted is “RuntimeError:…

It's error message blindness, similar to ad blindness. Even if you make a great banner ad with some very useful information, or the perfect and affordable product for my life I won't see it because I mentally filter out ads because they are junk most of the time.

Some people develop the same with relation to error messages because most of them are not actionable, other than "stuff broke somehow, [gibberish] blabla". Even if your error message is impeccable, it's in the class of things that are noise.

If you come up to me at some busy tourist location, where I'm used to lots of scammers, I won't listen to you even if you are actually a nice person and just want to have a nice chat and we would be compatible friends.

Often it is a good strategy to just ask people. Documentation and comments get out of date very fast. If you are the kind of person who reads everything meticulously and googles around, reads manuals etc. you may be wasting a lot of time. Of course there is a right balance to find. Some people err too much on the side of not thinking themselves and immediately asking for handholding, but overall it's often the right thing to do.

In many cases I found that trying to reason out what was going on was hopeless, because when I eventually gave up and asked someone, it turned out that the solution was unguessable, something like "ah of course, that things is out of date, do this magic incantation, then this and that, yeah we should update the docs sometime!".

A lot of knowledge is locked up inside people's brains and just spreads around as "rumors" on the grapevine. Is that state of affairs ideal? No. But it's realistic and people are going to adapt by asking first, thinking second.

Re: Write better error messages

#125

Post by mceachen »

alisonatwork wrote: post #101
marklubi wrote: post #87

Earlier quoted context omitted.

The trick that I've found is that each error message needs to be unique... not just the stack trace, but the actual wording of the message leading up to that. Get a screenshot or the exact verbatim of it, and you can identify exactly where in the code it originated. User reports are unreliable, but when I can pinpoint where the message originated from, it massively cuts down on the troubleshooting time.

A useful thing here is not just to include a unique error code for the type of error (usually numeric), but also to generate some kind of short Base32 or similar hash and print that right next to the error message while logging it to your normal back end. Then whether people send you a screen shot, copy/paste, whatever, you can easily search the logs to find the exact event that occurred.

Better still: add a unique prefix to the error code, so it's googlable.

The Typescript team does this with compilation errors, like `TS12345: frobulating types cannot be transmuted`.

Re: Write better error messages

#127

Post by mi_lk »

BerislavLopac wrote: post #118
legulere wrote: post #100

Earlier quoted context omitted.

In RFC 7807 all errors get an unique URI. Message texts might change or be translated into a language you don’t understand.

To be precise, each error type gets a unique URI. A good way to take advantage of that is to have a central database of all error types, but not many companies bother to do that.

> have a central database of all error types

do you have any example?

Re: Write better error messages

#128

Post by bonoboTP »

Kalium wrote: post #112
0xbadcafebee wrote: post #103

Earlier quoted context omitted.

The problem is here: "RuntimeError:" . Once they saw that, they stopped reading. "Did not find ENVVAR" [..] "ensure this is set to the proper value" [..] "and then restart the service" are also obscure and will stop them from reading. Why is the user like this? Error message PTSD. Years of staring at obscure errors full of technical jargon that are not helpful to the user, has left them scared to even look at the con…

I tried exactly this approach! What I got was a bunch of developers copy-pasting the error message with helpful URL at me and demanding to know what they should do. The number who followed the link and fixed the problem themselves was shockingly small. Going out on a limb, I think we're all going astray by trying to parse the error messages our fellow developers are reacting to. A great many seem to handle any unfami…

They don't parse the error message as a natural language sentence talking to them. They take it as an opaque string, like a big error code. It literally passes through them without getting interpreted.

They learned that the affordances of these error messages are copy pasting into some place: a google search box, or a chat box asking for help. But it has no affordance of "interpret as an English sentence" for them.

Re: Write better error messages

#129

Post by 0xbadcafebee »

Kalium wrote: post #112
0xbadcafebee wrote: post #103

Earlier quoted context omitted.

The problem is here: "RuntimeError:" . Once they saw that, they stopped reading. "Did not find ENVVAR" [..] "ensure this is set to the proper value" [..] "and then restart the service" are also obscure and will stop them from reading. Why is the user like this? Error message PTSD. Years of staring at obscure errors full of technical jargon that are not helpful to the user, has left them scared to even look at the con…

I tried exactly this approach! What I got was a bunch of developers copy-pasting the error message with helpful URL at me and demanding to know what they should do. The number who followed the link and fixed the problem themselves was shockingly small. Going out on a limb, I think we're all going astray by trying to parse the error messages our fellow developers are reacting to. A great many seem to handle any unfami…

If that's the case, then these people may just need training. It's likely that nobody has ever sat them down and explained that they have a responsibility to investigate their own issue. Often people feel they have to rush to get something done, and that they can't take time to troubleshoot. But if their bosses explained that, actually, it's fine if your work is a little late due to troubleshooting, they might do it themselves more often. You also may need to provide back-pressure by interacting via email/ticket.

Re: Write better error messages

#130

Post by an_ko »

throw827474737 wrote: post #50
ddulaney wrote: post #32

Earlier quoted context omitted.

Logs can definitely be a form of documentation. I write software that is generally run low in the stack, quietly doing some mundane tasks that are business-critical but rarely thought about. If one of our clients has to mess with our software beyond the occasional update, that was a failing. Not all software is like this, but lots of it is -- its value is that no human needs to be involved. I need to write log messag…

If it is that simple, the why doesn't the code fix it itself? But no, usually there is 1/2/3 likely things, but it also could be anything else.. and that kind if unexpected errors even often have no default-fix. No, the most best thing is to point to the documentation which has that, and not printig out manpages of docs in error messages now. > I write software that is generally run low in the stack What stack, how l…

I don't want to have to hunt for documentation if it breaks. It may have been 30 years and everything but the binary has been lost, and the vendor is out of business. If in that situation all I get is an error code and a link to documentation that doesn't exist, I'd have to start reverse-engineering. And while doing so I'd definitely be cursing the coder who decided that saving a couple hundred bytes of space in a log file in the event of an "abort the program"-severity event was worth dumping this in my lap.
Post reply on HN