Return more nuanced errors

[MasterKale]

These suggestions were pulled out of a comment I made in #2062 (comment). This new issue pulls out the five new errors I'm proposing we add to WebAuthn to help restart conversation with a smaller amount of context to have to catch up on.

Proposed Change

Earlier this week I met with some colleagues internally and brainstormed some new error messages that would be nice to have as an RP that wants more visibility into why users are having issues signing in, and to potentially offer inline remediation advice:

UserCancelledError

For UserCancelledError, it would be great to pull this out of NotAllowedError as a new default error that gets returned after the user specifically cancels out of the modal experience. NotAllowedError is currently so overloaded it's difficult to understand whether the user experienced a legitimate issue with their browser + OS + authenticator, or simply decided to cancel out.

HybridPrerequisitesError

The thinking here is that there are prerequisites that must be met for the browser and/or platform to facilitate successful hybrid registration and auth. If these prerequisites aren't met, and the browser notifies the user of it...

...why not let this propagate through to the RP after the user cancels out? In response to this the RP could e.g. show custom UI to guide the user through setting everything up to try again.

UserHybridCancelError

Currently, browsers typically show the hybrid QR code to users when allowCredentials contains no locally usable credentials. An RP that could catch this kind of error after the user cancels out could better understand that the user cancelled out of the auth because they didn't know how to proceed, and guide the user accordingly.

Right now there's no way to understand this because an RP would receive a NotAllowedError in response to the user cancelling the modal experience.

UserVerificationError

Passkeys are typically paired with a requirement to perform UV, both during registration and auth. If the user clicks through the modal experience to create a passkey or try to auth, but has no authenticator available that can perform UV or can't enter the correct PIN or scan the correct biometric, can WebAuthn not let the RP know that that's why the user failed the ceremony? The browser definitely tells the user that this is the case...

U2F token in a userVerification:required registration ceremony

Security key PIN entry issue during auth ceremony

...so why not propagate this through to the RP?

I also pondered breaking this one up, into two separate errors:

1. UserVerificationSupportError (e.g. U2F token when UV is required)
2. UserVerificationCollectionError (e.g. User can't enter correct PIN or scan correct biometric)

...but maybe these are less useful/too complex for a single "UserVerificationError" 🤔

TimeoutError

If the user clicks to start a WebAuthn ceremony but gets distracted and walks away to the point that the ceremony times out, couldn't that signal be sent to the RP? It's not quite a true "error" that happened, which it can currently appear to be due to the currently ambiguous NotAllowedError, but would be helpful nonetheless in understanding that nothing actually went wrong during the ceremony.

---

Anyway as I mentioned earlier these were new errors that came out of a brainstorming session. I'd love to hear your thoughts, and welcome any suggestions from other RP's on other types of errors that we could try to incorporate into WebAuthn for sake of better understanding of the user's interaction with WebAuthn.

[MasterKale]

I've created an Explainer here to help communicate more of the intent behind the proposed new error codes:

https://github.com/w3c/webauthn/wiki/Explainer:-New-Error-Codes-(2024-Edition)

[emlun]

Without judgement of the proposed errors, some spec formalia: currently, most WebAuthn errors are instances of DOMException with different names. The DOMException names table section of the WebIDL spec states that:

When creating or throwing a DOMException, specifications must use one of these names. If a specification author believes none of these names are a good fit for their case, they must file an issue to discuss adding a new name to the shared namespace [...]

So if we're going to continue using DOMException for all of these errors (I currently don't know any arguments for nor against it), we may need to pick from the already existing names, or generalize the error names enough that they can be upstreamed and useful in other contexts.

Fortunately, TimeoutError already exists, and OptOutError seems like a suitable match for UserCancelledError. The others are trickier to find existing matches for, though.

As summarized in #2047 (thanks!), the errors we already use are AbortError, ConstraintError, InvalidStateError, NotAllowedError, NotSupportedError, SecurityError and UnknownError (hm, turns out TypeError is not a DOMException but a simple exception). Adding TimeoutError and OptOutError to that, and removing deprecated names, the remaining ones are:

• DataCloneError: The object can not be cloned.
• DataError: Provided data is inadequate.
• EncodingError: The encoding operation (either encoded or decoding) failed.
• HierarchyRequestError: The operation would yield an incorrect node tree.
• InUseAttributeError: The attribute is in use by another element.
• InvalidCharacterError: The string contains invalid characters.
• InvalidModificationError: The object can not be modified in this way.
• InvalidNodeTypeError: The supplied node is incorrect or has an incorrect ancestor for this operation.
• NamespaceError: The operation is not allowed by Namespaces in XML.
• NetworkError: A network error occurred.
• NoModificationAllowedError: The object can not be modified.
• NotFoundError: The object can not be found here.
• NotReadableError: The I/O read operation failed.
• OperationError: The operation failed for an operation-specific reason.
• QuotaExceededError: The quota has been exceeded.
• ReadOnlyError: The mutating operation was attempted in a "readonly" transaction.
• SyntaxError: The string did not match the expected pattern.
• TransactionInactiveError: A request was placed against a transaction which is currently not active, or which is finished.
• VersionError: An attempt was made to open a database using a lower version than the existing version.
• WrongDocumentError: The object is in the wrong document.

I don't think any of these are good matches for HybridPrerequisitesError, UserHybridCancelError or UserVerificationError. The only somewhat-applicable one would be OperationError, but only because it's so unspecific it could apply to anything.

So maybe we need to use DOMException derived interfaces for these errors? Maybe a WebAuthenticationError with an enum-like DOMString cause attribute, for example.

[stephenmcgruer]

Fortunately, TimeoutError already exists, and OptOutError seems like a suitable match for UserCancelledError. The others are trickier to find existing matches for, though.

As a note, we added OptOutError very recently for a specific use-case we had in Secure Payment Confirmation that didn't seem to be covered by existing DOMException types. That is, the WHATWG is open to adding new DOMException names, so please don't feel constricted by that!

[jaiminbhatt7]

Can we also add fine-grained errors in place of the NotSupportedError? These are the two scenarios I am thinking about:

1. Client doesn't support the requested extension
2. Client doesn't support the requested COSE algorithm

Finer grained error will help troubleshooting why a certain authenticator isn't working on RP side.

[timcappalli]

Client doesn't support the requested extension

Two things re: extensions:

1. Extensions are optional, so a WebAuthn ceremony will not fail because of an extension. If you request one and don't receive a response, it can be inferred that it isn't supported.
2. Extensions can be advertised via getClientCapabilities

[kzaky]

I want to +1 this, given that we observe users often face unclear or overloaded errors, which limit their ability to troubleshoot and understand next steps. This is based on feedback we constantly receive about WebAuthn registrations. Errors like NotAllowedError are particularly challenging, as they obscure whether the issue is due to user cancellation, device compatibility, or other factors. Introducing more specific errors would provide users with clearer guidance and improve the experience across browsers and RPs.

To support users better on our side, we reviewed common WebAuthn errors and mapped likely causes with recommended actions to help users navigate these issues effectively. Providing context-specific messages, as seen with other RPs, helps users receive actionable guidance to complete or troubleshoot registration. Having this supported in the spec would be ideal.