Node error guidelines

[mmalecki]

As a follow-up of a chat with @tjfontaine about making up a common standard about errors coming from Node.js core, documenting them and policies about compatibility of them across node versions:

What needs to be decided on?

• A common standard for errors coming from Node core, including properties and messages, based on https://www.joyent.com/developers/node/design/errors (but not taking it for granted).
• Policies about compatibility of errors across node versions (mostly error messages).

What needs to be done

• All errors coming from Node core need to be documented.
• Common standard needs to be applied to all errors in Node core.
• Differences between errors in v0.11 and v0.10 need to be found and merged according to policies about compatibility we agree upon.

I think that what we have right now is close to perfect when it comes to having a common standard. Most errors have a code property which allows them to be recognized.

Assuming we're okay with adding our own .code codes, I don't really see a point of adding a .name.

There are multiple issues for adding more information to errors from certain modules:

• net - better network error messages #7005 (PR in net: give better error messages #7285)
• fs - Add .flag to EACCES errors from the fs module. #7796, BUG: fs.rename gives incorrect error message on error #685
• tls - tls: better error messages for certificate validation errors #7460
• dns - Include host name in DNS error message if available #8089

As to policies about compatibility, I believe that in stable versions we should just stick to whatever's documented, since this is what we guarantee to the user to be stable. Since we aim to document all the properties we return, I think we should be just fine.

My mind isn't set on error messages yet. Should we document them? What do other runtimes do?

[chrisdickinson]

I'm working on adding documentation to errors, with a PR incoming soon. Here's a preview of what I've got so far.

[mmalecki]

Oh, glanced at this, looks awesome @chrisdickinson!
Will read more.

[jasnell]

@chrisdickinson ... any updates on this one?