Why is every WebAuthn failure a NotAllowedError?

For privacy, the spec deliberately collapses many distinct failures — user cancelled, timeout, no matching credential, user-verification refused — into a single NotAllowedError so a site cannot probe which authenticators a user has. You generally cannot tell these apart programmatically and should show one neutral retry message.

What does InvalidStateError mean during registration?

During create(), InvalidStateError means a credential for one of the IDs in excludeCredentials already exists on the authenticator. It is the intended signal that the user is already registered on that security key or platform authenticator, so you should prompt them to sign in instead.

When is SecurityError thrown?

SecurityError is thrown when the rp.id is not a registrable suffix of the page origin, when the page is not served over a secure context (HTTPS or localhost), or when WebAuthn is used inside a cross-origin iframe without permission. Check your relying party ID and origin.

How do I handle a timeout?

A timeout surfaces as NotAllowedError (not a dedicated error), because it is indistinguishable from a user cancellation. Set a sensible timeout value in the options, then on NotAllowedError offer a retry button rather than assuming a hard failure.

Is AbortError different from a user cancel?

Yes. AbortError is thrown only when you call abort() on an AbortController you passed via the signal option — for example to cancel conditional UI. A user dismissing the native prompt yields NotAllowedError instead.

FIDO2/WebAuthn Error Codes

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

WebAuthn and FIDO2 surface failures as DOMException objects whose name property tells you what went wrong. This reference lists the names thrown by navigator.credentials.create() and navigator.credentials.get(), what triggers each, and a clear message to show the user.

How it works

A WebAuthn ceremony returns a rejected promise on failure. You inspect the rejection’s name:

try {
  const cred = await navigator.credentials.get({ publicKey });
} catch (err) {
  if (err.name === "NotAllowedError") {
    // user cancelled, timed out, or no credential matched
  }
}

The platform intentionally limits how much detail it exposes. Most user-driven failures and timeouts collapse into a single NotAllowedError so that a website cannot fingerprint which authenticators or passkeys a person has. The errors you can distinguish are mostly developer mistakes — a wrong rp.id, an insecure context, an already-registered key, or an algorithm the authenticator does not support.

Notes and examples

InvalidStateError during registration is not a bug — it means excludeCredentials matched an existing credential, i.e. the user is already enrolled. Treat it as “already registered”.
SecurityError almost always means your relying party ID does not match the origin, or the page is not a secure context.
Never display a raw DOMException string. Map the name to one of the user messages below.
Because cancel and timeout both produce NotAllowedError, always provide a retry path rather than a dead end.