Ultimate WebAuthn Errors in Production Guide (2026)

1. Introduction#

In production, WebAuthn errors are confusing because browsers expose a small set of DOMException names (like NotAllowedError) that can represent multiple underlying causes. On top of that, the vast majority of "errors" - often above 95% in optimized large-scale deployments - are actually expected behavior (user aborted the operating system passkey prompt).

If you want the canonical definitions for these names, start with MDN DOMException. For WebAuthn-specific conditions that lead to these exceptions (and what browsers are required to enforce), see the W3C Web Authentication spec.

If you treat all errors as “bugs”, you’ll do the wrong things:

• you’ll pollute your error metrics with normal cancels
• you’ll miss real regressions hidden inside the mass of NotAllowedError
• you’ll ship UI that confuses users instead of helping them recover

In this article we answer:

• What do the most common WebAuthn error names usually mean in real traffic?
• How do you disambiguate NotAllowedError into actionable buckets (cancel vs timeout vs availability)?
• Why does the same error mean different things depending on the operation (conditional UI login vs modal login vs passkey creation vs conditional create)?
• What minimum context should you capture so "it failed" becomes a reproducible issue?

2. A Production Cheat Sheet#

If you only need a quick mapping to unblock debugging, start with this table. It’s biased toward what teams actually see in dashboards and support tickets.

One thing that's easy to miss: the same error.name can mean very different things depending on the operation type. Keep the operation context in mind as you read the sections below. In practice, passkey creation (registration) errors typically outnumber login errors by a wide margin - the table above applies to both, but creation is where most of the volume lives.

Next, we'll go deeper on NotAllowedError because it's the one you'll see the most and the one teams misinterpret most often.

3. NotAllowedError: The operation either timed out or was not allowed#

NotAllowedError often looks like "passkeys failed", but it's usually the platform telling you the user did not complete the OS UI. The key is to split it into buckets you can act on.

What you'll see in the browser console:

All of these surface as error.name === "NotAllowedError". The error.message differs by browser engine and underlying cause, but the result is the same: the ceremony did not complete.

This applies to both login and passkey creation. During login (conditional UI, modal with or without allowList), NotAllowedError typically means the user didn't complete the ceremony. During passkey creation, the same error surfaces for different reasons: the user dismissed the creation dialog (conditional create did not work, or the page lost focus during an auto-triggered append. The operation type changes what the error means and what you should do about it.

Timing is often an underrated signal. An error after less than a second of a click is usually an immediate rejection (environment can't do it, document not focused, missing capability). An error after a few seconds is a user cancel (they saw the dialog and decided not to proceed). An error after 30+ seconds is a timeout. On native platforms, timing is especially important: authenticator round-trips, biometric prompts and credential manager handoffs all have characteristic durations that help you separate "didn't work" from "user walked away". You still can't distinguish easily if a passkey existed.

3.1 Disambiguate with Context#

You don't need a perfect signal. You need enough context to avoid treating every NotAllowedError the same way. iOS/Safari gets specific attention below because it has unique constraints (user activation requirements in earlier versions), but in raw error volume, Windows and Chromium browsers often generate more NotAllowedError than any other platform. These signals often get you 80% of the way:

This is also why NotAllowedError should rarely be user-visible. It’s not a message the user can act on.

One nuance that matters in production: some user agents may surface timeouts as TimeoutError, but many teams still see timeouts collapse into NotAllowedError in dashboards. Either way, treat timeouts as “ceremony did not complete” and bucket using timing plus context.

3.2 UX Handling: make Cancel a normal Exit#

When the OS sheet is dismissed or times out, your UI should immediately recover and react gracefully. A practical set of rules:

• restore the login UI (no spinners that keep running)
• keep identifier state (don’t force re-entry)
• show a visible fallback on the same screen
• avoid scary banners for expected outcomes

Beyond the basics:

• Treat the first abort as normal and offer a retry with a calm explanation. Only after a second abort should you suggest fallback options (see passkey fallback and recovery).
• Allow up to three creation prompts before a cooldown so surprised users get a second chance (see passkey creation best practices).
• Split error counts between creation and logins so you compare like with like.
• Segment error rates by OS, browser and device so you can spot where friction actually lives (see passkey login best practices).

If your “cancels” are genuinely high, the next step is to fix the root causes behind them: prompt timing, QR surprises and low availability.

3.3 Engineering Fixes that reduce NotAllowedError#

Start with the changes that move metrics quickly:

• Fix prompt timing and user activation (especially on iOS/Safari): Safari WebAuthn user-activated events.
• Reduce QR/hybrid surprises: why passkey flows show QR codes and users abandon.
• Gate offers so passkeys are shown when likely to succeed: offer passkeys only when they are likely to succeed.
• Use patterns that avoid prompting when no local credential exists: WebAuthn immediate mediation.
• Gate ceremonies with detection APIs so environment failures don't inflate your NotAllowedError bucket. Start with isUVPAA() as the most basic gate, then use getClientCapabilities() for finer checks (conditional create, conditional get, hybrid transport, platform authenticator). Be aware that detection APIs can break with OS updates: iOS 26.2 shipped a WebKit bug where isUVPAA() returns false on all WKWebView-based browsers even though passkeys work fine, causing sudden NotAllowedError spikes for 10-25% of iOS users (see fixing passkey detection with getClientCapabilities()).

3.4 Note on evolving Error Names#

Error names are a moving target. There are ongoing proposals to add more granular WebAuthn errors (for example, to separate “no credential available” from “user cancelled”). As of February 2026, this is not implemented in any browsers, so it’s still worth building your own reason buckets based on context and timing. If you want to track this work, see WebAuthn issue #2062 and the "New Error Codes" explainer.

The remaining error names are less frequent but still worth understanding when they appear.

4. AbortError: The operation was aborted#

AbortError is uncommon in volume compared to NotAllowedError, but when it appears it's highly diagnostic: it usually means the ceremony did not finish because your app invalidated the request - navigation happened, state changed, or a second request started.

What you'll see in the browser console:

Common production causes include:

• multiple concurrent WebAuthn calls (two prompts racing)
• route change/re-render during an in-flight ceremony
• calling AbortController.abort() during retries or state cleanup

To fix it, focus on making the ceremony a “critical section”:

• allow only one in-flight request at a time
• block navigation during the ceremony (or cancel cleanly and restore UI)
• treat abort as expected control flow: show a retry button and a fallback method

If you see AbortError concentrated in embedded surfaces or multi-domain apps, the next bucket to check is SecurityError.

5. SecurityError: WebAuthn is not supported on sites with TLS certificate errors#

SecurityError is the browser telling you: "this context is not allowed to do what you asked." In practice it's almost always configuration, not user behavior. In mature production deployments, SecurityError is rare because these issues are typically caught during integration testing. If it appears in production, it usually means a new domain, embedding context, or deployment target was added without proper WebAuthn configuration.

Common causes include:

• RP ID / origin mismatch (multi-domain setups)
• cross-origin embedding restrictions (iframes)
• insecure context (not HTTPS) or blocked permissions/policies
• .well-known/webauthn or .well-known/assetlinks.json misconfigured, missing, or temporarily unavailable. Network issues during the critical window when the browser fetches these files will cause failures. A common blind spot: if your homepage is down for maintenance, the well-known files are also offline, breaking passkey ceremonies across all relying parties that depend on them.

What you'll see in the browser console:

In production, SecurityError is rare - these are almost always caught during integration testing. When they do appear, the TLS certificate error is the most common survivor.

The fastest debugging loop is:

• log the origin and RP ID inputs you used
• reproduce in the same context (top-level vs iframe, prod domain vs staging)
• if you embed login, confirm permissions policy is configured (for example publickey-credentials-create / publickey-credentials-get): MDN Permissions-Policy
• verify your domain strategy (see related origins)
• if you use iframes, validate feature policies (see iframe passkeys)

Once SecurityError is handled, the next bucket to treat seriously is the set of errors that often indicate implementation bugs: InvalidStateError, ConstraintError and DataError.

6. InvalidStateError, ConstraintError, DataError: treat as Implementation Bugs#

These errors should be rare in a mature passkey implementation. When they show up, they usually indicate that option generation is wrong for a segment or that the flow is in the wrong state.

6.1 InvalidStateError: "credentials already registered with the relying party"#

What you'll see in the browser console:

Typical meanings:

• registration: you attempted to create a credential that already exists (duplicate)
• login: less common; often means the flow/state is inconsistent for the platform

Practical handling:

• if it happens in manual registration, treat it as “already enrolled” and route accordingly
• ensure excludeCredentials lists all existing credential IDs for the user so the authenticator can detect duplicates (see excludeCredentials)
• during conditional create, InvalidStateError is expected and should be silently ignored: it means a passkey already exists in the provider. The same applies to NotAllowedError and AbortError during conditional create (see conditional create on Chrome)

6.2 ConstraintError#

Typical meaning: the authenticator can’t satisfy your requested constraints.

Common triggers:

• missing device screen lock (especially Android): the platform requires biometric or PIN verification but the device has no lock screen configured
• too-strict authenticatorAttachment or resident key assumptions
• hard userVerification requirements in segments where they're not available

Fix: relax constraints (where acceptable) or provide an alternative path. For missing screen lock, consider detecting this condition and guiding users rather than failing silently (Android).

6.3 DataError#

Typical meaning: inputs are malformed or inconsistent.

Common triggers:

• encoding mistakes (base64 vs base64url)
• invalid credential ids / challenge formatting

Fix: validate and normalize inputs at the boundary where you generate WebAuthn options. In practice, DataError is effectively absent in mature production systems - if your option generation is tested, you won't see this in dashboards.

If these errors are under control, the next question is coverage: are users failing because the environment can’t do WebAuthn the way you expect?

7. NotSupportedError: The user agent does not support public key credentials#

NotSupportedError is a coverage signal, not a reliability signal. It usually means a segment can't do what you asked (OS/browser too old, missing capability, feature not enabled).

What you'll see in the browser console:

The first two are genuine NotSupportedError DOMExceptions. The TypeError entries are technically a different exception type but represent the same class of problem: the browser or environment doesn't support what you asked for. The JSON serialization TypeError family is far more common in practice than the NotSupportedError DOMException itself (see below).

Common causes include:

• older browsers/OS versions that don't support basic WebAuthn
• requesting WebAuthn features not available on that platform
• attempting platform-specific flows on unsupported devices

The JSON serialization family is the largest source of NotSupportedError-class failures in production. Technically these surface as TypeError (missing method), not as a DOMException, but this is where you'll encounter them. Two distinct root causes:

1. Browser doesn't support WebAuthn JSON serialization methods. The browser has navigator.credentials but not PublicKeyCredential.parseCreationOptionsFromJSON / parseRequestOptionsFromJSON. This accounts for roughly 90% of this error family, concentrated in older Safari and Chrome versions. If your client library depends on these methods without a fallback, this produces significant error volume.
2. Password manager extensions break .toJSON(). Extensions like Bitwarden, LastPass, or 1Password can intercept the ceremony and return an object that looks like a credential but isn't a real PublicKeyCredential instance. Calling .toJSON() on it either throws, returns undefined, or the object is null entirely. This is roughly 10% of the family but especially confusing to debug because the error messages differ by browser (Safari: "Can only call on instances of PublicKeyCredential"; Firefox: "does not implement interface PublicKeyCredential").

Handling should be blunt and fast:

• fall back immediately to fallback password/OTP
• record the segment so you can quantify coverage gaps
• avoid showing passkey CTAs on segments that will consistently fail

If coverage looks fine but failures still happen in specific segments, you may be dealing with platform-layer issues surfaced as UnknownError.

8. UnknownError: An unknown error occurred while talking to the credential manager#

UnknownError is a catch-all for authenticator/OS failures that don't map cleanly into the other categories. It's often transient, but it can also spike after OS updates.

What you'll see in the browser console:

Practical handling:

• use retry-friendly UX (don't "blame the user")
• capture OS/build numbers and credential-manager/provider context where possible
• watch for segment-specific spikes after OS updates

One niche source of errors that doesn't fit neatly into any DOMException category: password manager browser extensions (like Bitwarden, LastPass, 1Password, and others) can intercept WebAuthn API calls and return non-standard responses. While small in volume compared to user cancellations, these are worth tracking because they affect specific user segments consistently and the symptoms are confusing: missing methods on the returned credential object, unexpected error types, or malformed responses that don't match any documented WebAuthn error. These often surface as UnknownError or as unclassified exceptions. If you see error spikes concentrated in specific browsers with no OS-level explanation, check whether a credential manager extension is involved.

So far we've covered web browser error names. But if you also ship native apps, the error landscape is different - and in some ways, significantly better.

9. A Word on native Apps (iOS and Android)#

Everything above covers web browsers. Native apps - iOS with the ASAuthorization framework, Android with Credential Manager - share the same fundamental error categories but differ in important ways:

1. "No credentials" is a distinct signal. On web, browsers collapse "no credential available" and "user cancelled" into the same NotAllowedError for privacy. On native, using preferImmediatelyAvailableCredentials on iOS (ASAuthorizationController) or setPreferImmediatelyAvailableCredentials(true) on Android (GetCredentialRequest) tells the OS to only present credentials already on the device and fail immediately if none exist. This gives you a clean "no credentials" return that web cannot provide.

2. Credential provider status is visible. Native platforms in some conditions you can tell you when no credential provider (Google Password Manager, iCloud Keychain, 1Password, etc.) is installed, configured, or set as default and react to that. On web, this information is hidden behind opaque NotAllowedError messages.

3. Error messages are more specific. Because the user has installed the app - and thereby established a trust relationship with the relying party - the OS surfaces more diagnostic detail. The privacy considerations that force web browsers to be vague don't apply in the same way when the app is already on the device. iOS returns localized messages in the user's device language. Android returns structured error types with cause chains. This makes debugging easier but means your error handling must account for localization and platform-specific error formats.

9.1 iOS (ASAuthorization Framework)#

iOS surfaces passkey errors through two related frameworks. The error domain and code depend on whether you're creating or asserting a credential.

Passkey creation (registration):

Passkey login (assertion):

Localized "no credentials" messages (iOS only):

When preferImmediatelyAvailableCredentials is set and no passkey exists, iOS returns a localized error in the user's device language. This is unique to native apps - web browsers never expose this signal. The message always starts with The operation couldn't be completed. followed by the localized text:

English-locale devices typically resolve "no credentials" at the API level before the ASAuthorization framework returns a localized error, which is why no English variant appears above.

9.2 Android (Credential Manager API)#

Android surfaces passkey errors through the Credential Manager API (androidx.credentials). Error messages include a primary message and often a cause with additional detail. Compared to iOS, Android provides more structured error types and more explicit causes for configuration issues.

User cancellation and credential detection:

Configuration and security errors:

Platform and authenticator errors:

10. What to log so Errors become debuggable#

Most of the error classification in this article can be done with client-side signals alone. A frontend-only observability SDK captures enough context to classify the vast majority of WebAuthn errors. This is also how Corbado’s observability SDK is architected: the client-side layer handles error attribution, timing, operation context and platform detection. Server-side logging adds a second layer for failures that only the backend can see.

The key requirement: every attempt must be joinable end-to-end. A shared correlation id (e.g. auth_flow_id) connects client-side context with the server verification outcome.

10.1 Client-Side Signals (Frontend SDK)#

10.2 Server-Side Signals (Backend Verification)#

Server verification failures happen after the browser returns a credential and signed challenge. These should be structured errors with explicit codes, not mixed into the same bucket as client-side DOMException names. See: WebAuthn server implementation.

If you want a full funnel model (drop-offs by step and conversion between steps), see: passkey telemetry to understand drop-offs.

With this data in place, the conclusion becomes simple: most “errors” become either UX fixes, coverage fixes, or configuration fixes. But building and maintaining this classification yourself is significant ongoing work.

11. Beyond Error Names: how Corbado turns raw Errors into actionable Signals#

The logging checklist above captures raw signals. In production at scale, error.name alone is not enough. Building this classification yourself is significant ongoing work: error messages change with every browser and OS release, password manager providers ship updates that alter ceremony behavior and new error signatures appear with every feature launch.

11.1 Why error.name alone is not enough#

The same NotAllowedError can mean six different things depending on three dimensions browsers don't separate for you:

11.2 What Corbado's observability SDK captures#

This is the problem Corbado's observability SDK is built to solve. It is a lightweight frontend integration that sits on top of your existing passkey implementation, works with any WebAuthn server and any IDP, and classifies every WebAuthn error along all three dimensions automatically:

This is the Observe layer: visibility into what's happening, without changing your implementation.

11.3 Two Ways to debug: Top-Down and Bottom-Up#

Corbado's management console supports two investigation paths:

Top-down (dashboard to root cause):

1. Start with aggregate dashboards showing KPIs like Android login rate or iOS append success rate.
2. Notice a metric dipping. Drill into the funnel for that specific segment (e.g. native app on Android).
3. Compare against other segments (iOS, web) to confirm whether the issue is isolated or systemic.
4. From there, jump directly into the error time series, or ask the AI Analytics Assistant to cross-correlate whether errors have increased and run z-value anomaly analysis.

Bottom-up (error patterns to impact):

1. Start from the error classification view. Review classified error patterns and their volumes.
2. Refine error mappings as new patterns emerge (e.g. a new browser version shipping a different error message).
3. Errors are cross-correlated with KPI changes and surfaced as annotations on dashboards, so a spike in a specific error pattern is automatically linked to the metric it affected.

Both paths converge: top-down tells you something is wrong, bottom-up tells you why. The AI Analytics Assistant connects the two by letting you ask questions in natural language across both error data and adoption metrics.

Teams that want to act on these signals can move to Adopt, which adds passkey intelligence to automatically gate ceremonies, optimize enrollment prompts and heal broken passkey states. For regulated environments or hyperscale deployments, Enterprise adds single-tenant hosting, SIEM integration and PSD2-compliant configuration.

12. Conclusion#

WebAuthn error names are not a verdict. They're hints - and they only become actionable when you connect them to the operation type, the timing and the platform context.

• What do the most common WebAuthn error names mean in production? Most map to a small set of layers: user control flow (NotAllowedError), app lifecycle/concurrency (AbortError), security context/config (SecurityError), or option/state bugs (InvalidStateError, ConstraintError, DataError). The vast majority of volume is NotAllowedError, and most of that is expected behavior (user dismissed the prompt).
• How do you disambiguate NotAllowedError? Use timing (immediate rejection vs user cancel vs timeout), a QR/hybrid indicator (availability mismatch), user-activation context (especially on iOS/Safari) and the operation type (conditional UI vs modal login vs passkey creation vs conditional create). Don't treat all NotAllowedError as one failure mode.
• Why does the operation type matter? The same error.name during a conditional UI login is a completely different signal than during a conditional create or a manual passkey creation (user dismissed dialog). Logging the operation type alongside the error is what turns generic NotAllowedError into an actionable bucket.
• What minimum context makes errors debuggable? Capture error.name, operation type, time-to-error from operation start, flow type, whether QR/hybrid UI was shown, OS/browser/device (including versions), a correlation id (auth_flow_id) and server verification rejects as explicit codes.

Two rules of thumb that cut across all error types: never show raw browser errors to users - always provide a clear fallback path - and separate local attempts from QR/hybrid cross-device attempts, because they fail for different reasons and need different fixes. At scale, maintaining error classification across browsers, OS versions, and credential managers is ongoing work. Consider using an observability SDK with a maintained pattern library rather than building this from scratch.