Apple Passkey Error Codes: Complete Reference (2026)

Apple's passkey error system has multiple layers and most developers only see the surface. The public ASAuthorizationError codes (1000-1010) are intentionally broad - Apple compresses dozens of specific failure modes into a handful of categories before they reach your app or Safari.

Want to find out how many people use passkeys?

View Adoption Data

Under the hood, Apple's passkey error stack is a 3-layer translation pipeline: specific codes from the AuthenticationServicesAgent daemon, translated to public ASAuthorizationError codes in AuthenticationServices, then translated again to DOMExceptions for Safari. At each layer, information is lost. This article maps every layer completely.

This reference covers Apple's error codes as observed in macOS 26.2 (Tahoe), iOS 26.2 and iOS 18.4 simulator runtimes. The error code tables are identical between iOS and macOS.

What this article covers vs related articles:

• For web browser errors (DOMExceptions like NotAllowedError and AbortError): see WebAuthn Errors in Production
• For Android error codes: see GPS Passkey Error Codes
• For native deployment strategy and abort rate analysis: see Native App Passkey Errors
• This article: the Apple error codes, 3-layer translation pipeline and Safari vs native visibility

Every passkey error on iOS flows through a 3-layer pipeline before reaching your app or Safari. Understanding these layers explains why logging only ASAuthorizationErrorFailed can lead to missing the actual failure reason.

flowchart TD
  subgraph layer1 ["Layer 1: Private XPC Daemon"]
    ASCAgent["AuthenticationServicesAgent <br>(ASCAuthorizationErrorDomain) <br>Codes 0-22"]
  end

  subgraph layer2 ["Layer 2: Public Framework"]
    ASAuth["ASAuthorizationController<br>(ASAuthorizationErrorDomain)<br>Public codes 1000-1010"]
  end

  subgraph layer3_safari ["Layer 3a: Safari/WebKit"]
    Safari["WebAuthenticatorCoordinatorProxy<br>→ DOMException<br>(NotAllowedError, InvalidStateError...)"]
  end

  subgraph layer3_native ["Layer 3b: Native App"]
    NativeApp["Your app receives<br>ASAuthorizationError<br>+ full public code set (1000-1010)"]
  end

  subgraph biometric ["Biometric Layer"]
    LA["LAContext<br>(LAErrorDomain)<br>Codes -1 to -14"]
  end

  ASCAgent --> ASAuth
  LA --> ASCAgent
  ASAuth --> Safari
  ASAuth --> NativeApp

Want to experiment with passkey flows? Try our Passkeys Debugger.

Try for Free

The public error domain that native apps and Safari see. 11 codes, stable across iOS versions with new additions.

Apple has been systematically extracting specific failure modes out of the generic Failed (1004) bucket across iOS versions. This is the most important practical trend for passkey error handling:

On iOS 26, the remaining cases that still need 1004 + NSUnderlyingErrorKey unwrapping are increasingly narrow: primarily security key operations (ASC codes 4, 8, 9, 10, 13, 20, 21) which require physical hardware. Apple is gradually solving the information-loss problem at the API level rather than requiring developers to dig into private error domains.

When you receive an ASAuthorizationError, several userInfo keys carry diagnostic information:

Inspecting NSUnderlyingErrorKey is a standard iOS error handling practice, not something specific to passkeys. Many iOS SDKs use this two-level unwrap pattern where the public error code gives you the category and the underlying error gives you the root cause:

• Firebase iOS Auth docs explicitly state: "When investigating or logging errors, review the userInfo dictionary. NSUnderlyingErrorKey contains the underlying error that caused the error in question."
• Atomic iOS SDK demonstrates casting to NSError, reading userInfo[NSUnderlyingErrorKey] and handling @unknown default across every error callback
• RevenueCat's error utilities wrap backend and StoreKit errors into public error codes with the original preserved in NSUnderlyingErrorKey
• The same domain/code matching pattern applies to Foundation errors like FileManager where the surface error hides the actual POSIX cause

In theory, this same pattern should help dig deeper into passkey failures - inspecting the underlying ASCAuthorizationError behind a generic ASAuthorizationErrorFailed (1004) could reveal whether the cause is "iCloud Keychain is off" or "security key PIN is locked." In practice however, our POC testing on iOS 26.2 found that NSUnderlyingErrorKey was nil for every native passkey scenario we triggered (domain association failures, missing credentials). The diagnostic detail was in localizedDescription and NSLocalizedFailureReasonErrorKey instead. This suggests that while NSUnderlyingErrorKey is well-established in other Apple frameworks, passkey errors on modern iOS rely more on dedicated public codes and localized description strings than on the underlying error chain.

The private error domain generated by Apple's AuthenticationServicesAgent XPC daemon. These codes are expected to surface via NSUnderlyingErrorKey at runtime based on disassembly analysis, though runtime confirmation is limited to WebKit-originated and device-configuration error paths. The following table covers codes present in macOS 26.2.

Note that ASC code 5 (no credentials) and code 7 (duplicate credential) - the two most common "interesting" codes - are now surfaced via dedicated public codes on modern iOS: code 5's scenario is handled by 1005 (NotInteractive) when using preferImmediatelyAvailableCredentials, and code 7's scenario is handled by 1006 (MatchedExcludedCredential) on iOS 18+. The primary value of this ASCAuthorizationError table is for security key debugging and understanding older iOS behavior.

Code 7 has three distinct code paths based on runtime device state:

Authentication Analytics Whitepaper:
Track passkey adoption & impact on revenue.

Get Whitepaper

The 3-layer translation is the core of Apple's error pipeline. Here is the complete mapping from ASCAuthorizationError to public ASAuthorizationError as observed in macOS 26.2 and iOS 26.2.

Safari and native apps receive the same ASAuthorizationError from Layer 2, but Safari then translates it to a DOMException (Layer 3a) while native apps retain the full public code set. Codes 1005, 1006, 1009 and 1010 are native-app-only signals that Safari collapses into generic DOMExceptions.

Subscribe to our Passkeys Substack for the latest news.

Subscribe

Based on analysis of production passkey SDKs, these are the most common mistakes in Apple passkey error handling:

• String matching on localizedDescription for error classification. Some SDKs use patterns like error.localizedDescription.contains("No credentials available for login.") or error.localizedDescription.contains("is not associated with domain"). This only works on English-language devices. Apple localizes these messages into 30+ languages. Use error codes for classification, not strings.
• Mapping unknown codes to "cancelled." Some SDKs have default: → .cancelled in their switch statement, which means codes 1005, 1009, 1010 all silently become "user cancelled." Unknown codes should map to "unknown" not "cancelled" - a code you don't recognize is not the same as a user dismissal.
• Not handling codes added in newer iOS versions. If your switch statement doesn't have cases for 1005, 1006, 1009, 1010, those codes fall into your default case. Add explicit cases for all known codes and use a safe default for future codes.
• Using plain default instead of @unknown default. Plain default silences the compiler when Apple adds new codes (which they've done in every major release recently: iOS 15 added 1005, iOS 18 added 1006-1008, iOS 26 added 1009-1010). Using @unknown default gives you a compiler warning on SDK upgrade, prompting you to handle new cases explicitly. The runtime behavior is identical.

A simple example of handling codes structurally, with #available checks for newer codes and string matching only as a last resort for the ambiguous 1001 case:

func authorizationController(controller: ASAuthorizationController,
                             didCompleteWithError error: Error) {
    guard let authorizationError = error as? ASAuthorizationError else {
        handleUnknownError(error)
        return
    }
 
    // iOS 18+: dedicated code for duplicate credential
    if #available(iOS 18.0, macOS 15.0, *) {
        if authorizationError.code == .matchedExcludedCredential {
            handleDuplicateCredential()
            return
        }
    }
 
    // iOS 26+: dedicated codes for device config and Sign in with Apple preference
    if #available(iOS 26.0, macOS 26.0, *) {
        if authorizationError.code == .deviceNotConfiguredForPasskeyCreation {
            handleDeviceNotConfigured()
            return
        }
        if authorizationError.code == .preferSignInWithApple {
            handlePreferSignInWithApple()
            return
        }
    }
 
    switch authorizationError.code {
    case .canceled:  // 1001
        // On older iOS without preferImmediately, "no credentials"
        // can arrive as 1001 with a localized message.
        // String matching is a pragmatic last resort for this ambiguous case.
        if error.localizedDescription.contains("No credentials available") {
            handleNoCredentials()
        } else {
            handleUserCancelled()
        }
 
    case .notInteractive:  // 1005 (iOS 15+)
        // Clean signal: no credentials on this device for this RP.
        // No UI was shown. Offer passkey creation or fall back to password.
        handleNoCredentials()
 
    case .failed:  // 1004
        // Generic bucket. The localizedDescription contains the actual reason.
        // e.g. "Application with identifier X is not associated with domain Y"
        if error.localizedDescription.contains("not associated with domain") {
            handleDomainNotAssociated()
        } else {
            // Check NSUnderlyingErrorKey for security key details
            let nsError = error as NSError
            if let underlying = nsError.userInfo[NSUnderlyingErrorKey] as? NSError,
               underlying.domain == "ASCAuthorizationErrorDomain" {
                handleASCError(code: underlying.code)
            } else {
                handleGenericFailure(error)
            }
        }
 
    case .invalidResponse,
         .notHandled,
         .unknown:
        handleUnknownError(error)
 
    @unknown default:
        // IMPORTANT: do NOT map unknown codes to "cancelled".
        // @unknown default triggers a compiler warning when Apple adds new codes.
        handleUnknownError(error)
    }
}

Biometric failures fire before passkey operations complete. These errors come from LAContext and surface as part of the passkey flow when user verification is required.

In practice, the most important LA errors for passkey reliability are -5 (no passcode - passkeys cannot work), -8 (biometric lockout - temporary, passcode fallback available) and -4 (system cancel - transient, retry appropriate).

Beyond the structured error codes, the Apple frameworks contain dozens of diagnostic strings that appear in logs, crash reports and error userInfo dictionaries.

Get free passkey whitepaper for enterprises.

Get for free

Always log beyond the ASAuthorizationError code. Three practical points: (1) for many 1004 errors, localizedDescription contains the actual diagnostic (e.g. "Application with identifier X is not associated with domain Y") - not NSUnderlyingErrorKey, which may be nil; (2) AuthenticationServices failures sometimes contain NSMultipleUnderlyingErrorsKey instead of a single NSUnderlyingErrorKey; and (3) NSError objects in userInfo are not JSON-serializable - convert to strings or dictionaries before sending to analytics.

func logPasskeyError(_ error: Error, operation: String) {
    let nsError = error as NSError
 
    var logEntry: [String: Any] = [
        "operation": operation,
        "domain": nsError.domain,
        "code": nsError.code,
        "description": String(describing: error)
    ]
 
    if let failureReason = nsError.localizedFailureReason {
        logEntry["failure_reason"] = failureReason
    }
 
    if let underlying = nsError.userInfo[NSUnderlyingErrorKey] as? NSError {
        logEntry["underlying"] = [
            "domain": underlying.domain,
            "code": underlying.code,
            "description": underlying.localizedDescription
        ]
    }
 
    if let multiple = nsError.userInfo[NSMultipleUnderlyingErrorsKey] as? [NSError] {
        logEntry["underlying_multiple"] = multiple.map {
            ["domain": $0.domain, "code": $0.code, "description": $0.localizedDescription]
        }
    }
 
    if let userMessage = nsError.userInfo["ASAuthorizationErrorUserVisibleMessageKey"] as? String {
        logEntry["user_visible_message"] = userMessage
    }
 
    analytics.log("passkey_error", properties: logEntry)
}

The robust fields (domain, code, localizedDescription, localizedFailureReason, NSUnderlyingErrorKey) are public API and stable across iOS versions. The ASAuthorizationErrorUserVisibleMessageKey is a framework-specific userInfo key - log it when present but do not depend on it for user-facing messages. Instead, map known ASAuthorizationError.Code values to your own strings for display and use the raw underlying error details for debugging.

For the broader native reliability picture including Android vs iOS abort rate analysis, see Native App Passkey Errors.

The key takeaway from Apple's passkey error stack is that Apple is progressively solving the information-loss problem at the API level. Each iOS release extracts specific failure modes from the generic code 1004 into dedicated codes: 1005 for no credentials (iOS 15), 1006 for duplicate credentials (iOS 18), 1010 for device not configured (iOS 26). On modern iOS, the most common passkey failures all have clean, dedicated signals that require no string matching or error unwrapping.

For the Android error code reference, see GPS Passkey Error Codes. For the web browser error perspective, see WebAuthn Errors in Production. For setting up your analytics framework, see Passkey Analytics.

Igor Gjorgjioski

Head of Digital Channels & Platform Enablement, VicRoads

Corbado proved to be a trusted partner. Their hands-on, 24/7 support and on-site assistance enabled a seamless integration into VicRoads' complex systems, offering passkeys to 5 million users.

Passkeys that millions adopt, fast. Start with Corbado's Adoption Platform.

Start Free Trial