When reporting errors, note what value was invalid and why

[Zac-HD]

I've regularly had to debug problems with unusual or slightly broken data - or my misunderstanding of various layers of the software stack -, and I can't be the only one. For example:

• open_mfdataset tries to open an invalid file. Which file? Why is it invalid?
  (one was truncated when the download crashed - I had to find it by size)
• Xarray can't convert a dtype. What dtype couldn't it convert? And of what variable? (it was a boolean mask)

And of course there are many more examples. This manifesto has some good advice, but in essence:

• Think about the information a new user will need to understand what has gone wrong and fix their code. It's good to be verbose here, because new users need this information most and experienced users won't see it anyway (or might be glad it's there on occasion!).
• Report:
  • The value that was invalid
    (or a summary that rules out validity; eg shape and dtype for arrays)
  • The operation that was attempted
  • Why the value was invalid in this operation
  • If possible, what the user can do to fix this

This is quite an open-ended issue; as well as the code changes it probably requires some process changes to ensure that new errors are equally helpful. Ultimately, the goal is for errors to become a positive aid to learning rather than a frustrating barrier.

[shoyer]

Thanks for raising this concern. I think we have been gradually improving the quality of our error messages, but I agree that we still have a large opportunity for improvement.

This also one area where someone inexperienced can have a big impact. Experienced developers are likely to gloss over confusing error messages (or not see them at all) because they already understand what's going on. Any GitHub issues you open when you encounter an error that was not as helpful as possible would be gratefully appreciated.

I've been trying to collect these under the error reporting tag:
https://github.com/pydata/xarray/issues?q=is%3Aopen+is%3Aissue+label%3A%22error+reporting%22

Our contributing guidelines (see #1485) should make it clear that full code to reproduce is not required for such cases.

Potentially it would also make sense to audit some of our code line by line to check that error messages are as good as possible.

cc @jhamman

[stale]

In order to maintain a list of currently relevant issues, we mark issues as stale after a period of inactivity

If this issue remains relevant, please comment here or remove the stale label; otherwise it will be marked as closed automatically

[Zac-HD]

It's at least out of date, and doesn't appear to be helpful, so I'm happy to close this issue.