Repository navigation
meta: semver impact of Error messages #13937
Description
Activity
Since this is tagged
ctc-review, @nodejs/ctcI don’t have a strong personal opinion about this, but I see @mscdex’ point, and I would be okay with considering these semver-major while Node 8 is Current (but trying to clearly message that that is going to change with the next major version).
Generally I don't see the point in pushing it out further like that. Switching to the new mechanism is already semver-major which means the overwhelming majority of changes in this area already won't be in 8.x at any point in time. Those that are in 8.x were also semver-major changes that users will already be adapting to -- which involves moving away from checking the error message text in favor of checking the code. Requiring that these all be semver-major while 8.x is current won't provide any tangible benefit.
Reacted by Colin Ihrig, Benjamin Gruenbaum, Ruben Bridgewater and Timothy GuShould this be put on the LTS WG agenda? I'm OK with LTS being the final arbiter on what is and isn't a breaking change. (And if that isn't written into their charter, perhaps it ought to be?)
Reacted by Benjamin Gruenbaum(Might also be good to clarify if LTS WG is the small-ish number of people listed in the LTS repo README or the considerably larger group of people on the @nodejs/lts team.)
(Might also be good to clarify if LTS WG is the small-ish number of people listed in the LTS repo README or the considerably larger group of people on the @nodejs/lts team.)
Reacted by Rich TrottI'd like to see a citgm run - I think we can actually test if this must be semver major or not relatively quickly. I'm not sure on what PR I should run the citgm run against though - would love assistance with that.
- Reacted by Anthony DelgadoReacted by Anthony Delgado
I think we can actually test if this must be semver major or not relatively quickly
IMHO this is one of those things where end user code could be just as easily affected as modules on npm.
Reacted by Anthony DelgadoReacted by Anthony DelgadoReacted by Anthony Delgado@mscdex my point was that if CITGM is red (and it is red) we have to mark it semver-major (and we should). Since it breaks stuff in the ecosystem we can be sure it breaks user code.
We should also probably notify those 50 packages in NPM about the breakage.
I'm thinking we need a communications push along with some period of time for people to adjust. Ideally we'd have all of the messages moved over and then do a fair bit of communications/evangelism. Its going to be easier to say it applies to all messages than explaining a different policy based on the message.
For messages that we have moved over (semver-major) and are changing again the main question to me is if there has been enough communication/knowledge transfer so that developers know that they should no longer be checking the error message and instead use the error code so that they don't get affected by the second change. Until then I was thinking it would be safer to continue to mark them as semver-major.
@mhdawson it will take some time. Module author needs to adjust, and old versions of Node.js phase out. I would say we should wait until Node 10 goes LTS, i.e. we might stop considering these changed after 2 current releases (one of which LTS) with the new system.
33 remaining items
Was there any discussion of my suggestion for a cross-node core-included error code package?
Was there any discussion of my suggestion for a cross-node core-included error code package?
@ljharb No. TBH I encouraged us to make a decision on whether these are breaking changes, and to discuss other issues (2-CTC approval issues, how to get the new errors implemented faster, etc.) in GitHub issues.
Reacted by Jordan Harband@ljharb I believe @jasnell talked about making the internal error system an npm package that readable-stream can depend on?
EDIT: oh I see it is already mentioned in #13937 (comment), it currently needs a bit of work to work on older versions of node.
Reacted by Jordan HarbandWas there any discussion of my suggestion for a cross-node core-included error code package?
AFAICT That's orthogonal. Maybe if it's up and running and adopted, we could trigger a reevaluation of the severity policy.
P.S. I have been thinking of way to assemble a map of error messages to error code, efficiently, and across release line... Not so trivial 🤔
Reacted by Jordan Harband- added a commit that references this issue
on Jul 21, 2017 - added a commit that references this issue
on Jul 22, 2017 - added a commit that references this issue
on Jul 24, 2017 I read in this article https://medium.com/the-node-js-collection/node-js-errors-changes-you-need-to-know-about-dc8c82417f65 that there is a plan to change the
error.nameto contain the 'code' as part of the name string likeCustomErrorName [ERROR_CODE]. I think this is a bad idea because:- A common strategy for handling errors up until now involve setting a custom name before throwing the error and then later checking the error name with
if (err.name == 'NotAuthorizedError'); if we start adding error codes as part of the name string likeNotAuthorizedError [SOME_ERROR_CODE]then it would break backwards compatibility with respect to that error handling strategy. - Adding the error code to the error name would be different from how the JavaScript
error.nameappears in the browser which does not contain any error code or brackets as part of the error name. Being as consistent with browsers as possible is a good thing.
Reacted by Felix Becker- A common strategy for handling errors up until now involve setting a custom name before throwing the error and then later checking the error name with
there is a plan to change the error.name to contain the 'code' as part of the name string like CustomErrorName [ERROR_CODE]. I think this is a bad idea...
@jondubois valid comment, so just to be clear this change will only affect Errors that
nodecore it throwing. AFAIK there is no plan to touch "userland" Errors in any way.
For example if you did:dgram.createSocket('i like rabbits')
core would throw
new Error('Bad socket type specified. Valid types are: udp4, udp6');
now instead the Error will have a
codeand it's name will include it:{ code: 'ERR_SOCKET_BAD_TYPE', type: Error, message: /^Bad socket type specified\. Valid types are: udp4, udp6$/ name: `Error [ERR_SOCKET_BAD_TYPE]` }
I agree that adding the code to the
nameis weird. For menameis a programmatically-inspectable property, just likecode, and not for "human consumption" likemessage. Having pretty formatting in there with a space and brackets goes against that.
Browser errors have nocodeproperty, they always usename, so that's where this intuition is coming from. For example, forfetchyou would have to check iferr.name === 'AbortError'. The only other option is usinginstanceof, but that is bad practice (assert on interfaces, not implementations).Personally I see
codeas a subcategory ofname, e.g.namecan beTypeErrorandcodeERR_SOCKET_BAD_TYPE. It's both useful to be able to make assertions about the broader category of and error as well as the exact error reason. For example, in an Express error handler, I might want to never return anyTypeErrors to the client because they are programming errors. Or take p-retry as an example (emphasis mine):Returns a Promise that is fulfilled when calling input returns a fulfilled promise. If calling input returns a rejected promise, input is called again until the max retries are reached, it then rejects with the last rejection reason.
It doesn't retry on TypeError as that's a user error.Checking
codehere wouldn't be helpful.I would prefer if both
nameandcodeare for programmatic inspection without fancy formatting, andError.prototype.toString()could be modified to include botherror.nameanderror.codein the output, astoString()is unarguably purely for human consumption. Doing this for all errors, including user errors, would be a great feature and encourage users to make use of error codes too. Alternatively it could only be an internal base error class.encourage users to make use of error codes too
Please, allow us to set
error.codeas well as the message from the constructor if you want to do this.throw new Error("Message", "ERR_CODE");
@haykam821 that's part of the JS language itself, and is not something node should do. You can do
Object.assign(new Error('message'), { code: 'ERR_CODE' })if you need to.Though, Node can (and in my opinion - should) expose helper function for creating errors with code.
Eventually, perhaps. For now the focus is on making sure all of node.js' own errors have assigned codes and consistent error messages
Reacted by Ruben Bridgewater and haykam821
masterContext
There is an ongoing effort to migrate all JS expectations throws by
nodecore to have a.codeproperty. The error code allows userland to react in different exceptions specific ways.To that extent a new internal module (
internal/errors) was created #11220 and the migration is tracked in #11273 (and to less extent in https://github.com/nodejs/node/projects/4) Some module migrations landed innode@v8.0.0, some have landed inmastersince, and some have yet to be migrated. Hence it can't be asserted thatnodecore will only throw errors with an error-code, and so we have to assume the existence of userland code that depends onerror.messageparsing.Issue
At present there seems to be a difference of opinions as to the semver level of changes in messages of
internal/errors.Action item
A consensus should be reached on this issue as we want to have a clear path forward, and unambiguous guidelines for contributors.
Relevant discussion
guides/using-internal-errors.mdinternal/errors: improve ERR_INVALID_ARG_TYPE #13730 (comment)
internal/errors: improve ERR_INVALID_ARG_TYPE #13730 (comment) (landed as
semver-patchbut markeddon't land on v8.xuntil discoution is concluded)errors: improve invalid arg type #13834 (comment)
[EDIT by @Trott:
don't land->don't land on v8.xfor clarity.]