Der ultimative Guide für WebAuthn-Fehler in Produktion (2026)

In Produktion sind WebAuthn-Fehler oft verwirrend, da Browser nur eine kleine Menge an DOMException-Namen (wie NotAllowedError) offenlegen, die verschiedene zugrundeliegende Ursachen haben können. Zudem sind die allermeisten "Fehler" – in optimierten, großen Implementierungen oft über 95 % – tatsächlich erwartetes Verhalten (der Nutzer hat den Passkey-Prompt des Betriebssystems abgebrochen).

Experimentieren Sie mit Passkey-Flows im Passkeys Debugger.

Kostenlos testen

Wenn Sie die kanonischen Definitionen für diese Namen suchen, beginnen Sie mit MDN DOMException. Für WebAuthn-spezifische Bedingungen, die zu diesen Ausnahmen führen (und was Browser erzwingen müssen), siehe die W3C Web Authentication Spec.

Wenn Sie alle Fehler als „Bugs“ behandeln, tun Sie das Falsche:

• Sie verfälschen Ihre Fehlermetriken durch normale Abbrüche.
• Sie übersehen echte Regressionen, die sich in der Masse an NotAllowedError verbergen.
• Sie liefern eine UI aus, die Nutzer verwirrt, anstatt ihnen bei der Wiederherstellung zu helfen.

In diesem Artikel beantworten wir:

• Was bedeuten die häufigsten WebAuthn-Fehlernamen normalerweise im echten Traffic?
• Wie unterteilen Sie NotAllowedError in handlungsrelevante Kategorien (Abbruch vs. Timeout vs. Verfügbarkeit)?
• Warum bedeutet derselbe Fehler je nach Operation (Conditional UI Login vs. modaler Login vs. Passkey-Erstellung vs. Conditional Create) etwas anderes?
• Welchen Mindestkontext sollten Sie erfassen, damit aus einem "Es ist fehlgeschlagen" ein reproduzierbares Problem wird?

Wenn Sie nur eine schnelle Übersicht zur Fehlersuche benötigen, beginnen Sie mit dieser Tabelle. Sie konzentriert sich darauf, was Teams in Dashboards und Support-Tickets tatsächlich sehen.

Eines wird leicht übersehen: Derselbe error.name kann je nach Operationstyp völlig unterschiedliche Dinge bedeuten. Behalten Sie den Kontext der Operation im Hinterkopf, wenn Sie die folgenden Abschnitte lesen. In der Praxis übertreffen Erstellungsfehler (Registrierung) Login-Fehler meist bei Weitem – die obige Tabelle gilt für beides, aber bei der Erstellung liegt das größte Volumen.

Als Nächstes gehen wir detaillierter auf den NotAllowedError ein, da dies der Fehler ist, den Sie am häufigsten sehen werden und der von Teams am häufigsten falsch interpretiert wird.

Ein NotAllowedError sieht oft so aus, als ob "Passkeys fehlgeschlagen" wären, aber meist teilt Ihnen die Plattform lediglich mit, dass der Nutzer die OS-UI nicht abgeschlossen hat. Der Schlüssel ist, dies in Kategorien zu unterteilen, auf die Sie reagieren können.

Was Sie in der Browser-Konsole sehen werden:

All diese Meldungen treten als error.name === "NotAllowedError" auf. Die error.message variiert je nach Browser-Engine und zugrundeliegender Ursache, aber das Ergebnis ist dasselbe: Die Zeremonie wurde nicht abgeschlossen.

Dies gilt sowohl für den Login als auch für die Passkey-Erstellung. Beim Login (Conditional UI, modal mit oder ohne allowList) bedeutet ein NotAllowedError typischerweise, dass der Nutzer die Zeremonie nicht beendet hat. Bei der Passkey-Erstellung tritt derselbe Fehler aus anderen Gründen auf: Der Nutzer hat den Erstellungsdialog geschlossen, Conditional Create hat nicht funktioniert oder die Seite hat während eines automatisch ausgelösten Appends den Fokus verloren. Der Operationstyp ändert, was der Fehler bedeutet und was Sie tun sollten.

Timing ist oft ein unterschätztes Signal. Ein Fehler in weniger als einer Sekunde nach einem Klick ist meist eine sofortige Ablehnung (Umgebung kann es nicht, Dokument nicht fokussiert, fehlende Fähigkeit). Ein Fehler nach einigen Sekunden ist ein Nutzerabbruch (sie haben den Dialog gesehen und sich dagegen entschieden). Ein Fehler nach über 30 Sekunden ist ein Timeout. Auf nativen Plattformen ist das Timing besonders wichtig: Authenticator-Roundtrips, biometrische Prompts und Credential-Manager-Übergaben haben alle charakteristische Dauern, die Ihnen helfen, ein "Hat nicht funktioniert" von einem "Nutzer ist weggegangen" zu unterscheiden. Sie können dennoch nicht ohne Weiteres unterscheiden, ob ein Passkey existierte.

Sie benötigen kein perfektes Signal. Sie brauchen genug Kontext, um zu vermeiden, dass jeder NotAllowedError gleich behandelt wird. iOS/Safari wird unten speziell behandelt, da es besondere Einschränkungen hat (Anforderungen an die Nutzeraktivierung in früheren Versionen), aber was das reine Fehlervolumen betrifft, generieren Windows und Chromium-Browser oft mehr NotAllowedError als jede andere Plattform. Diese Signale bringen Sie oft zu 80 % ans Ziel:

Das ist auch der Grund, warum ein NotAllowedError selten für den Nutzer sichtbar sein sollte. Es ist keine Nachricht, auf die der Nutzer reagieren kann.

Die Kontext-Klassifizierung ist auch der Bereich, in dem sich die Erfolgsraten am deutlichsten unterscheiden. Die Passkey-Erfolgsratenanalyse des Corbado Passkey-Benchmarks 2026 misst im ersten Quartal 2026 eine Abschlussrate von 55–95 % für Identifier-First-Flows auf unbekannten Geräten, verglichen mit 95–99 % für wiederkehrende Nutzer auf bekannten Geräten über große B2C-Implementierungen hinweg. Web-Identifier-First auf iOS erreicht 85–95 % Abschluss (% CDA 0–5 %), Android Web 70–85 % (% CDA 5–10 %) und macOS Web 70–85 % (% CDA 10–15 %), während Windows Web bei 45–60 % Identifier-First-Abschluss liegt, mit % CDA bei 55–65 % unter Windows 11 und 40–55 % unter Windows 10. Das Lesen des NotAllowedError-Volumens ohne Trennung von Kontexten auf bekannten und unbekannten Geräten vermischt zwei grundlegend unterschiedliche Erfolgsregime.

Eine Nuance, die in Produktion wichtig ist: Einige User-Agents zeigen Timeouts als TimeoutError an, aber viele Teams sehen in Dashboards, dass Timeouts unter NotAllowedError zusammengefasst werden. Behandeln Sie Timeouts in jedem Fall als „Zeremonie wurde nicht abgeschlossen“ und klassifizieren Sie anhand von Timing plus Kontext.

Wenn der OS-Dialog geschlossen wird oder ein Timeout auftritt, sollte sich Ihre UI sofort erholen und elegant reagieren. Ein praktisches Set an Regeln:

• UI für das Login wiederherstellen (keine unendlich ladenden Spinner)
• Identifier-Status beibehalten (keine erneute Eingabe erzwingen)
• Sichtbaren Fallback auf demselben Bildschirm anzeigen
• Beängstigende Warnhinweise für erwartete Ergebnisse vermeiden

Darüber hinaus:

• Behandeln Sie den ersten Abbruch als normal und bieten Sie einen erneuten Versuch mit einer ruhigen Erklärung an. Erst nach einem zweiten Abbruch sollten Sie Fallback-Optionen vorschlagen.
• Erlauben Sie bis zu drei Erstellungs-Prompts vor einem Cooldown, damit überraschte Nutzer eine zweite Chance erhalten.
• Trennen Sie Fehlerzählungen nach Erstellung und Logins, damit Sie Äpfel mit Äpfeln vergleichen.
• Segmentieren Sie Fehlerraten nach OS, Browser und Gerät, damit Sie erkennen können, wo tatsächliche Reibungspunkte liegen.

Wenn Ihre „Abbrüche“ wirklich hoch sind, ist der nächste Schritt, die Grundursachen dahinter zu beheben: Prompt-Timing, QR-Überraschungen und geringe Verfügbarkeit.

Beginnen Sie mit Änderungen, die Metriken schnell verbessern:

• Prompt-Timing und Nutzeraktivierung korrigieren (insbesondere bei iOS/Safari).
• QR/Hybrid-Überraschungen reduzieren.
• Passkey-Angebote so platzieren, dass sie nur angezeigt werden, wenn sie wahrscheinlich erfolgreich sind.
• Muster verwenden, die keine Prompts auslösen, wenn keine lokale Credential vorhanden ist.
• Umgang mit Netzwerkinstabilitäten: Netzwerkfehler während der Überprüfung äußern sich oft als generische clientseitige Fehler. Implementieren Sie eine Offline-Warteschlange für Ihre Telemetrie-Logs, damit keine Fehlerdaten verloren gehen, wenn die Verbindung des Nutzers während der Zeremonie abbricht.
• Zeremonien durch Erkennungs-APIs absichern, damit Fehler der Umgebung Ihre NotAllowedError-Kategorie nicht aufblähen. Beginnen Sie mit isUVPAA() als Basisüberprüfung und nutzen Sie dann getClientCapabilities() für feinere Prüfungen (Conditional Create, Conditional Get, Hybrid Transport, Platform Authenticator). Beachten Sie, dass Erkennungs-APIs durch OS-Updates kaputtgehen können: iOS 26.2 lieferte einen WebKit-Bug aus, bei dem isUVPAA() in allen WKWebView-basierten Browsern false zurückgibt, obwohl Passkeys problemlos funktionieren, was zu plötzlichen Spitzen bei NotAllowedError für 10 bis 25 % der iOS-Nutzer führte.

Fehlernamen sind im Wandel. Es gibt aktuelle Vorschläge, granulare WebAuthn-Fehler einzuführen (z. B. um „keine Credential verfügbar“ von „Nutzer hat abgebrochen“ zu trennen). Stand Februar 2026 ist dies noch in keinem Browser implementiert, daher lohnt es sich nach wie vor, eigene Ursachen-Kategorien basierend auf Kontext und Timing aufzubauen. Wenn Sie diese Arbeit verfolgen möchten, siehe WebAuthn-Issue #2062 und den "New Error Codes" Explainer.

Die übrigen Fehlernamen treten seltener auf, sollten aber dennoch verstanden werden, wenn sie auftauchen.

Ein AbortError tritt im Vergleich zum NotAllowedError selten in großen Mengen auf, aber wenn er auftaucht, ist er stark diagnostisch: Er bedeutet normalerweise, dass die Zeremonie nicht abgeschlossen wurde, weil Ihre App die Anfrage ungültig gemacht hat – es fand eine Navigation statt, der Status änderte sich oder eine zweite Anfrage wurde gestartet.

Was Sie in der Browser-Konsole sehen werden:

Häufige Ursachen in Produktion sind:

• mehrere gleichzeitige WebAuthn-Aufrufe (zwei Prompts im Wettlauf)
• Routenänderung/Re-Render während einer laufenden Zeremonie
• Aufruf von AbortController.abort() während Wiederholungsversuchen oder beim Aufräumen des Status

Um das Problem zu beheben, konzentrieren Sie sich darauf, die Zeremonie zu einem „kritischen Bereich“ zu machen:

• Erlauben Sie nur eine laufende Anfrage zur gleichen Zeit
• Blockieren Sie Navigation während der Zeremonie (oder brechen Sie sauber ab und stellen Sie die UI wieder her)
• Behandeln Sie den Abbruch als normalen Kontrollfluss: Zeigen Sie einen Wiederholen-Button und eine Fallback-Methode an

Wenn sich AbortError in eingebetteten Ansichten oder Multi-Domain-Apps häuft, ist der nächste zu prüfende Bereich SecurityError.

Ein SecurityError ist die Mitteilung des Browsers: „Dieser Kontext darf nicht tun, was Sie verlangt haben.“ In der Praxis handelt es sich fast immer um ein Konfigurationsproblem, nicht um Nutzerverhalten. In ausgereiften Produktionsimplementierungen sind SecurityError selten, da diese Probleme typischerweise bei Integrationstests aufgefangen werden. Wenn sie in der Produktion auftreten, bedeutet dies normalerweise, dass eine neue Domain, ein Einbettungskontext oder ein Deployment-Ziel ohne ordnungsgemäße WebAuthn-Konfiguration hinzugefügt wurde.

Häufige Ursachen sind:

• RP-ID-/Origin-Unstimmigkeiten (Multi-Domain-Setups)
• Einschränkungen durch Cross-Origin-Einbettungen (iFrames)
• Unsicherer Kontext (nicht HTTPS) oder blockierte Berechtigungen/Richtlinien
• .well-known/webauthn oder .well-known/assetlinks.json ist falsch konfiguriert, fehlt oder ist vorübergehend nicht verfügbar. Netzwerkprobleme während des kritischen Zeitfensters, in dem der Browser diese Dateien abruft, führen zu Ausfällen. Ein häufiger blinder Fleck: Wenn Ihre Startseite wegen Wartungsarbeiten offline ist, sind auch die well-known Dateien offline, was Passkey-Zeremonien für alle auf sie angewiesenen Relying Parties beeinträchtigt.

Was Sie in der Browser-Konsole sehen werden:

In der Produktion ist ein SecurityError selten – diese werden fast immer in Integrationstests abgefangen. Wenn sie dennoch auftreten, ist ein TLS-Zertifikatsfehler die häufigste verbleibende Ursache.

Der schnellste Debugging-Prozess lautet:

• Loggen Sie die verwendeten Origin- und RP-ID-Eingaben
• Reproduzieren Sie das Problem im selben Kontext (Top-Level vs. iFrame, Produktions-Domain vs. Staging)
• Wenn Sie das Login einbetten, prüfen Sie, ob die Permissions-Policy konfiguriert ist (zum Beispiel publickey-credentials-create / publickey-credentials-get): MDN Permissions-Policy
• Validieren Sie Ihre Domain-Strategie
• Wenn Sie iFrames nutzen, prüfen Sie die Feature-Policies

Sobald der SecurityError gelöst ist, sind die nächsten wichtigen Fehler InvalidStateError, ConstraintError und DataError, die oft auf Implementierungsfehler hindeuten.

Passkeys-Cheatsheet. Praxisnahe Leitfäden, Rollout-Muster und KPIs für Passkey-Programme.

Cheat Sheet erhalten

Diese Fehler sollten in einer reifen Passkey-Implementierung selten sein. Wenn sie auftreten, weisen sie meist darauf hin, dass die Optionsgenerierung für ein Segment fehlerhaft ist oder sich der Flow im falschen Zustand befindet.

Was Sie in der Browser-Konsole sehen werden:

Typische Bedeutungen:

• Registrierung: Sie haben versucht, ein Credential zu erstellen, das bereits existiert (Duplikat)
• Login: weniger häufig; bedeutet oft, dass der Ablauf/Zustand für die Plattform inkonsistent ist

Praktische Handhabung:

• Wenn es bei manueller Registrierung passiert, behandeln Sie es als "bereits registriert" und leiten Sie entsprechend weiter
• Stellen Sie sicher, dass excludeCredentials alle existierenden Credential-IDs für den Nutzer auflistet, damit der Authenticator Duplikate erkennen kann
• Bei Conditional Create ist ein InvalidStateError erwartet und sollte lautlos ignoriert werden: Es bedeutet, dass bereits ein Passkey im Provider existiert. Dasselbe gilt für NotAllowedError und AbortError bei Conditional Create (siehe Conditional Create on Chrome)

Typische Bedeutung: Der Authenticator kann die angeforderten Einschränkungen nicht erfüllen.

Häufige Auslöser:

• Fehlende Bildschirmsperre am Gerät (besonders bei Android): Die Plattform verlangt eine biometrische oder PIN-Verifikation, aber das Gerät hat keinen Lockscreen konfiguriert
• Zu strenge Anforderungen für authenticatorAttachment oder Resident Keys
• Harte userVerification-Anforderungen in Segmenten, in denen diese nicht verfügbar sind

Behebung: Einschränkungen lockern (sofern akzeptabel) oder einen alternativen Weg anbieten. Bei einer fehlenden Bildschirmsperre sollten Sie diese Bedingung erkennen und den Nutzer anleiten, anstatt stillschweigend zu scheitern (Android).

Typische Bedeutung: Eingaben sind fehlerhaft oder inkonsistent.

Häufige Auslöser:

• Kodierungsfehler (Base64 vs. Base64url)
• Ungültige Formate für Credential-IDs / Challenges

Behebung: Validieren und normalisieren Sie Eingaben an der Schnittstelle, an der Sie die WebAuthn-Optionen generieren. In der Praxis ist ein DataError in reifen Systemen praktisch nicht vorhanden – wenn Ihre Optionsgenerierung getestet ist, werden Sie dies nicht in Dashboards sehen.

Wenn diese Fehler unter Kontrolle sind, stellt sich als Nächstes die Frage nach der Abdeckung: Scheitern Nutzer, weil die Umgebung WebAuthn nicht auf die von Ihnen erwartete Weise ausführen kann?

Ein NotSupportedError ist ein Signal für Abdeckung, nicht für Zuverlässigkeit. Es bedeutet meist, dass ein Segment nicht in der Lage ist, die Anfrage auszuführen (OS/Browser zu alt, fehlende Funktion, Feature nicht aktiviert).

Was Sie in der Browser-Konsole sehen werden:

Die ersten beiden sind echte NotSupportedError DOMExceptions. Die Einträge unter TypeError sind technisch gesehen ein anderer Ausnahmetyp, repräsentieren aber dieselbe Fehlerklasse: Der Browser oder die Umgebung unterstützt das Angeforderte nicht. Die JSON-Serialisierungs-Familie der TypeError ist in der Praxis deutlich häufiger als die NotSupportedError DOMException selbst (siehe unten).

Häufige Ursachen sind:

• Ältere Browser/OS-Versionen, die grundsätzliches WebAuthn nicht unterstützen
• Anfordern von WebAuthn-Features, die auf dieser Plattform nicht verfügbar sind
• Versuch, plattformspezifische Flows auf nicht unterstützten Geräten auszuführen

Die JSON-Serialisierungs-Familie ist die größte Quelle für NotSupportedError-Fehler in Produktion. Technisch gesehen treten diese als TypeError (fehlende Methode) auf und nicht als DOMException, aber hier werden Sie ihnen begegnen. Es gibt zwei verschiedene Ursachen:

1. Browser unterstützt die WebAuthn JSON-Serialisierungsmethoden nicht. Der Browser verfügt über navigator.credentials, aber nicht über PublicKeyCredential.parseCreationOptionsFromJSON / parseRequestOptionsFromJSON. Dies macht etwa 90 % dieser Fehlerfamilie aus und konzentriert sich auf ältere Versionen von Safari und Chrome. Wenn Ihre Client-Bibliothek auf diese Methoden angewiesen ist, ohne einen Fallback anzubieten, erzeugt dies ein erhebliches Fehlervolumen.
2. Passwort-Manager-Erweiterungen brechen .toJSON(). Erweiterungen wie Bitwarden, LastPass oder 1Password können die Zeremonie abfangen und ein Objekt zurückgeben, das wie ein Credential aussieht, aber keine echte PublicKeyCredential-Instanz ist. Der Aufruf von .toJSON() darauf wirft entweder einen Fehler, gibt undefined zurück, oder das Objekt ist komplett null. Dies betrifft etwa 10 % der Familie, ist jedoch besonders schwer zu debuggen, da sich die Fehlermeldungen je nach Browser unterscheiden (Safari: "Can only call on instances of PublicKeyCredential"; Firefox: "does not implement interface PublicKeyCredential").

Die Handhabung sollte direkt und schnell sein:

• Sofort auf Passwort/OTP-Fallback ausweichen
• Segment erfassen, um Lücken in der Abdeckung zu quantifizieren
• Keine Passkey-CTAs in Segmenten anzeigen, die konsequent fehlschlagen

Wenn die Abdeckung in Ordnung scheint, Fehler aber dennoch in bestimmten Segmenten auftreten, haben Sie es möglicherweise mit Problemen auf Plattform-Ebene zu tun, die als UnknownError in Erscheinung treten.

Ein UnknownError ist ein Sammelbegriff für Fehler des Authenticators/OS, die nicht sauber in die anderen Kategorien passen. Er ist oft vorübergehend, kann aber auch nach OS-Updates vermehrt auftreten.

Was Sie in der Browser-Konsole sehen werden:

Praktische Handhabung:

• Nutzen Sie eine retry-freundliche UX (nicht "dem Nutzer die Schuld geben")
• Erfassen Sie OS/Build-Nummern und den Kontext des Credential-Managers/Anbieters, wo möglich
• Achten Sie auf segmentspezifische Spitzen nach OS-Updates

Eine besondere Fehlerquelle, die nicht sauber in eine DOMException-Kategorie passt: Passwort-Manager-Browsererweiterungen (wie Bitwarden, LastPass, 1Password und andere) können WebAuthn-API-Aufrufe abfangen und nicht-standardkonforme Antworten zurückgeben. Auch wenn diese im Vergleich zu Nutzerabbrüchen nur in geringem Umfang auftreten, lohnt es sich, sie zu tracken, da sie bestimmte Nutzersegmente beständig betreffen und die Symptome verwirrend sind: fehlende Methoden auf dem zurückgegebenen Credential-Objekt, unerwartete Fehlertypen oder fehlerhafte Antworten, die keinem dokumentierten WebAuthn-Fehler entsprechen. Diese treten oft als UnknownError oder unklassifizierte Ausnahmen in Erscheinung. Wenn Sie Fehlerspitzen bemerken, die sich auf bestimmte Browser konzentrieren, ohne dass es eine Erklärung auf OS-Ebene gibt, prüfen Sie, ob eine Credential-Manager-Erweiterung beteiligt ist.

Bislang haben wir Browser-Fehlernamen behandelt. Aber wenn Sie auch native Apps ausliefern, sieht die Fehlerlandschaft anders aus – und in mancher Hinsicht deutlich besser.

Alles bisherige bezieht sich auf Webbrowser. Native Apps – iOS mit dem ASAuthorization-Framework, Android mit dem Credential Manager – teilen sich die gleichen grundlegenden Fehlerkategorien, unterscheiden sich aber in wichtigen Aspekten:

1. "Keine Credentials" ist ein klares Signal. Im Web fassen Browser aus Datenschutzgründen "Kein Credential verfügbar" und "Nutzer hat abgebrochen" im NotAllowedError zusammen. Nativ können Sie durch preferImmediatelyAvailableCredentials bei iOS (ASAuthorizationController) oder setPreferImmediatelyAvailableCredentials(true) bei Android (GetCredentialRequest) dem OS mitteilen, dass nur bereits auf dem Gerät vorhandene Credentials angeboten werden sollen und sofort abgebrochen wird, falls keine existieren. Dies liefert eine klare "Keine Credentials"-Antwort, die im Web nicht möglich ist.

2. Status des Credential-Providers ist sichtbar. Native Plattformen können Ihnen unter Umständen mitteilen, wenn kein Credential-Provider (Google Password Manager, iCloud Keychain, 1Password etc.) installiert, konfiguriert oder als Standard festgelegt ist, sodass Sie darauf reagieren können. Im Web sind diese Informationen hinter undurchsichtigen NotAllowedError-Meldungen verborgen.

3. Fehlermeldungen sind spezifischer. Weil der Nutzer die App installiert hat – und damit eine Vertrauensbeziehung zur Relying Party aufgebaut hat – gibt das Betriebssystem mehr diagnostische Details preis. Die Datenschutzbedenken, die Browser dazu zwingen, vage zu bleiben, greifen nicht in gleicher Weise, wenn die App bereits auf dem Gerät ist. iOS liefert lokalisierte Nachrichten in der Gerätesprache des Nutzers. Android liefert strukturierte Fehlertypen mit Ursachenketten. Das erleichtert das Debugging, bedeutet aber, dass Ihre Fehlerbehandlung Lokalisierung und plattformspezifische Fehlerformate berücksichtigen muss.

iOS stellt Passkey-Fehler über das ASAuthorization-Framework bereit. Alle Fehler kommen im authorizationController(controller:didCompleteWithError:)-Delegate-Callback als NSError-Objekte an.

Klassifizieren Sie nach Domain + Code, nicht nach dem Nachrichten-String. Die primäre Fehler-Domain ist com.apple.AuthenticationServices.AuthorizationError (ASAuthorizationError.errorDomain). Casten Sie den Fehler mit let nsError = error as NSError und gleichen Sie .domain und .code ab. Nutzen Sie in Produktion niemals .localizedDescription für Vergleiche – Apples Nachrichten sind in über 30 Sprachen lokalisiert und können sich in neuen OS-Versionen ändern. Die unten aufgelisteten Meldungen sind nützlich, um Fehler in Logs zu erkennen, nicht aber als Kriterium zur Klassifizierung.

Öffentliche ASAuthorizationError Codes:

Der wichtigste Unterschied für die Produktion: Seit iOS 18 geben duplizierte Credentials ihren eigenen Fehlercode 1006 (MatchedExcludedCredential) zurück. Bei iOS 17 und älter waren Duplikate unter dem Code 1004 (Failed) verborgen. Ab iOS 18 ist die Unterscheidung strukturell (anderer Fehlercode), nicht textbasiert.

Häufige Laufzeitfehler (Referenz auf Log-Ebene):

Diese Nachrichten erscheinen in localizedDescription oder in userInfo für spezifische Fehler-Szenarien. Nutzen Sie sie für die Log-Suche und das Debugging, nicht für die programmatische Klassifizierung.

Lokalisierte "Keine Credentials"-Nachrichten (Code 1005):

Wenn preferImmediatelyAvailableCredentials gesetzt ist und kein Passkey existiert, gibt iOS Code 1005 (NotInteractive) mit einer lokalisierten Meldung in der Gerätesprache des Nutzers zurück. Dies ist einzigartig für native Apps – Webbrowser stellen dieses Signal nie zur Verfügung. Die Nachricht beginnt immer mit The operation couldn't be completed., gefolgt von dem lokalisierten Text:

(Beachten Sie, dass im obigen originalen Text keine deutsche Version stand, aber die Logik auf Code 1005 greift.)

Auf englisch-lokalisierten Geräten wird das Problem "Keine Credentials" normalerweise schon auf API-Ebene geklärt, bevor das ASAuthorization-Framework einen lokalisierten Fehler zurückgibt, weshalb dort keine englische Variante erscheint. Gleichen Sie programmgesteuert immer den Code 1005 ab, anstatt diese Strings zu analysieren.

Android liefert Passkey-Fehler über die Credential Manager API (androidx.credentials). Die Fehlermeldungen beinhalten eine Hauptmeldung und oft eine cause mit zusätzlichen Details. Im Vergleich zu iOS bietet Android strukturiertere Fehlertypen und explizitere Ursachen für Konfigurationsprobleme.

Nutzerabbruch und Credential-Erkennung:

Konfigurations- und Sicherheitsfehler:

Plattform- und Authenticator-Fehler:

Das folgende Diagramm zeigt, wie alle diskutierten Ebenen – Infrastruktur, Umgebung, Operationstyp, Klassifizierung und Erkennung – end-to-end zusammenwirken. Es ist das mentale Modell, das Sie im Kopf haben sollten, wenn Sie Ihr Fehler-Tracking entwerfen.

flowchart TD
    %% Global Styles
    classDef expected fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
    classDef unexpected fill:#ffebee,stroke:#c62828,stroke-width:2px;
    classDef network fill:#fff3e0,stroke:#ef6c00,stroke-dasharray: 5 5;
    classDef env fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px;
    classDef action fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;

    %% --- LEFT SIDE: NETWORK & SERVER ---
    subgraph Infrastructure ["Infrastruktur (Server/Netzwerk)"]
        direction TB
        ServerErr["Serverseitiger Fehler<br/>500 / Logikfehler"]:::network
        NetErr["Netzwerkfehler<br/>Timeout / 400 Bad Request"]:::network

        ServerErr & NetErr -->|Äußert sich als| ClientManifest["Clientseitiger generischer Fehler"]
    end

    %% --- CENTER: THE ENVIRONMENT STACK (From Sketch) ---
    subgraph Environment ["Die Umgebung (Clientseitig)"]
        direction TB

        %% Layer 1: Platform Type
        subgraph Type ["Ebene 1: Plattform"]
            Web["Web / Browser"]
            Native["Nativ / App"]
        end

        %% Layer 2: OS Context
        subgraph OS_Layer ["Ebene 2: OS & Version"]
            OS_Web["OS: Windows, macOS, Linux"]
            OS_Nat["OS: iOS, Android"]
            OS_Ver["OS Version / Einstellungen<br/>(Bildschirmsperre, Biometrie)"]

            Web --> OS_Web
            Native --> OS_Nat
            OS_Web & OS_Nat --> OS_Ver
        end

        %% Layer 3: Client Software
        subgraph Client_Layer ["Ebene 3: Client-Software"]
            Browser["Browser: Chrome, Safari, Edge<br/>+ Version"]
            App["Native App / WebView<br/>+ App-Version"]

            OS_Ver --> Browser
            OS_Ver --> App
        end

        %% Layer 4: WebAuthn Operation
        subgraph Op_Layer ["Ebene 4: WebAuthn Operation"]
            OpType{"Operationstyp"}

            Login["Login<br/>(navigator.credentials.get)"]
            Reg["Registrierung<br/>(navigator.credentials.create)"]

            Browser & App --> OpType
            OpType --> Login
            OpType --> Reg
        end

        %% Layer 5: Sub-types & Complexity
        subgraph Modality ["Ebene 5: Modalität & Komplexität"]
            Sub_CUI["CUI / Conditional UI"]
            Sub_Auto["Automatische Operation"]
            Sub_CDA["CDA / Cross-Device Auth"]

            Login & Reg --> Sub_CUI
            Login & Reg --> Sub_Auto
            Login & Reg --> Sub_CDA
        end
    end

    %% --- BOTTOM: CLASSIFICATION & ACTION (The "What here?" section) ---
    subgraph Analysis ["Fehleranalyse & Laufzeit"]
        direction TB

        %% Classification
        Classification{"Klassifizierung"}

        Exp["Erwarteter Fehler<br/>(Nutzer brach Zeremonie ab)"]:::expected
        Unexp["Unerwarteter Fehler<br/>(System/Absturz/Unbekannt)"]:::unexpected

        ClientManifest --> Classification
        Sub_CUI & Sub_Auto & Sub_CDA --> Classification

        Classification --> Exp
        Classification --> Unexp

        %% Detection Logic
        subgraph Detection ["Erkennungsziele"]
            P1["P1: Login-Probleme"]
            P2["P2: Erstellungs-Probleme"]
            Baseline["Baseline Drift erkennen<br/>(Anstieg erwarteter Fehler)"]
            NewErr["Neue Anomalien erkennen<br/>(Anstieg unerwarteter Fehler)"]
        end

        Exp --> Baseline
        Unexp --> NewErr
        Exp & Unexp --> P1 & P2

        %% Actionable Outcomes
        subgraph Action ["Maßnahmen zur Behebung"]
            Fix["Hotfix ausrollen / Neue Version"]:::action
            Fallback["Automatischen Fallback aktivieren<br/>(Passkey deaktivieren)"]:::action
        end

        P1 & P2 & NewErr --> Fix
        P1 & P2 & NewErr --> Fallback
    end

    %% Connectors
    Infrastructure -.-> Environment

Die zentrale Erkenntnis: Ein roher error.name ergibt erst dann einen Sinn, wenn Sie wissen, welche Ebene der Umgebung ihn erzeugt hat, welche Operation lief und ob der Fehler erwartet oder unerwartet war. Die folgenden Abschnitte behandeln, was zu protokollieren ist und wie man darauf reagiert.

Die meisten Fehlerklassifizierungen in diesem Artikel können allein mit clientseitigen Signalen erfolgen. Ein Frontend-only Observability-SDK erfasst ausreichend Kontext, um die große Mehrheit an WebAuthn-Fehlern zu klassifizieren. Auf diese Weise ist auch das Corbado Observability SDK aufgebaut: Die clientseitige Ebene kümmert sich um Fehlerzuordnung, Timing, Operationskontext und Plattformerfassung. Das serverseitige Logging fügt eine zweite Ebene für Fehler hinzu, die nur das Backend erkennen kann.

Die wesentliche Anforderung: Jeder Versuch muss durchgehend (end-to-end) verknüpfbar sein. Eine gemeinsame Korrelations-ID (z. B. auth_flow_id) verbindet den clientseitigen Kontext mit dem Ausgang der Serververifizierung.

Server-Verifizierungsfehler treten auf, nachdem der Browser ein Credential und eine signierte Challenge zurückgegeben hat. Dies sollten strukturierte Fehler mit expliziten Codes sein und nicht mit den clientseitigen DOMException-Namen in einen Topf geworfen werden.

Abonnieren Sie unseren Passkeys Substack für aktuelle News.

Abonnieren

Liegen diese Daten vor, wird die Schlussfolgerung einfach: Die meisten "Fehler" stellen sich als UX-Fixes, Abdeckungs-Fixes oder Konfigurations-Fixes heraus. Die Erstellung und Pflege einer solchen Klassifizierung in Eigenregie bedeutet jedoch einen erheblichen, dauerhaften Aufwand.

Die obige Logging-Checkliste erfasst Rohdaten. In einer produktiven, großen Umgebung reicht error.name allein nicht aus. Diese Klassifizierung selbst zu entwickeln, bedeutet stetige Arbeit: Fehlermeldungen ändern sich mit jeder neuen Browser- und OS-Version, Passwort-Manager-Anbieter liefern Updates, die das Zeremonie-Verhalten verändern, und neue Fehlersignaturen tauchen mit jedem Feature-Launch auf.

Derselbe NotAllowedError kann sechs verschiedene Ursachen haben, basierend auf drei Dimensionen, die Browser nicht für Sie auftrennen:

Genau für dieses Problem wurde das Corbado Observability SDK entwickelt. Es ist eine leichtgewichtige Frontend-Integration, die sich auf Ihre bestehende Passkey-Implementierung aufsetzt, mit jedem WebAuthn-Server und IDP funktioniert und automatisch jeden WebAuthn-Fehler entlang aller drei Dimensionen klassifiziert:

Dies ist die Observe-Schicht: Sichtbarkeit auf das, was passiert, ohne Ihre Implementierung zu ändern.

Die Corbado-Konsole unterstützt zwei Wege zur Problemanalyse:

Top-down (Vom Dashboard zur Ursache):

1. Nach zwei Arten von Anomalien suchen:
   • Gestiegene Erwartete Fehler (Baseline Drift): Hat eine spezifische Umgebung (z. B. iOS 18.2 auf iPhone 15) einen allmählichen Anstieg von "Nutzerabbrüchen" verzeichnet? Dies deutet oft auf eine neue UX-Reibung hin, die durch ein OS-Update eingeführt wurde.
   • Gestiegene Unerwartete Fehler (Spikes): Ein komplett neuer Fehler oder ein plötzlicher Anstieg an Fehlschlägen. Dies deutet meist auf eine Breaking Change (internes IDP-Update) oder eine Regression in einer neuen Browserversion hin.
2. Nach Impact priorisieren:
   • P1: Login-Probleme. Wenn die Login-Erfolgsraten fallen, sofort alarmieren.
   • P2: Erstellungs-Probleme. Trends beobachten, aber keine Entwickler wegen eines Anstiegs an "Nutzerabbrüchen" bei Erstellungen nachts wecken.
3. In die Umgebung drillen: Nutzen Sie die granularen Dimensionen (Hardware, Auth-Einstellungen), um einzugrenzen, ob das Problem global ist oder spezifisch für "Samsung-Geräte mit Android 14".
4. Behebung: Wenn ein kritischer Spike erkannt wird, haben Sie einen Kill-Switch bereit. Deaktivieren Sie Passkeys für diese spezifische Umgebung automatisch oder manuell und fallen Sie auf OTPs/Passwörter zurück, um die Login-Raten während der Untersuchung zu erhalten.

Bottom-up (Von Fehlermustern zur Auswirkung):

1. Starten Sie mit der Fehlerklassifizierungs-Ansicht. Prüfen Sie klassifizierte Fehlermuster und deren Volumen.
2. Verfeinern Sie Fehlerzuordnungen, sobald neue Muster auftauchen (z. B. eine neue Browserversion liefert eine veränderte Fehlermeldung).
3. Fehler werden mit KPI-Veränderungen korreliert und als Annotationen in Dashboards eingeblendet, sodass ein Spike in einem spezifischen Fehlermuster automatisch mit der Metrik verknüpft wird, die er beeinflusst hat.

Beide Pfade führen zusammen: Top-down sagt Ihnen, dass etwas nicht stimmt, Bottom-up verrät Ihnen warum. Der AI Analytics Assistant verbindet die beiden, indem er Ihnen erlaubt, Fragen in natürlicher Sprache sowohl zu Fehlerdaten als auch zu Adoptionsmetriken zu stellen.

Teams, die auf diese Signale reagieren möchten, können zu Adopt wechseln. Dies fügt Passkey-Intelligence hinzu, die Passkey-Angebote absichert, Prompts optimiert und fehlerhafte Passkey-Zustände repariert. Für regulierte Umgebungen gibt es Enterprise, was PSD2-konforme Konfigurationen und SIEM-Integration hinzufügt.

Kostenloses Passkey-Whitepaper für Unternehmen erhalten.

Kostenlos erhalten

WebAuthn-Fehlernamen sind kein endgültiges Urteil. Es sind Hinweise – und sie werden erst handlungsrelevant, wenn man sie mit dem Operationstyp, dem Timing und dem Plattform-Kontext verbindet.

• Was bedeuten die häufigsten WebAuthn-Fehlernamen in der Produktion? Die meisten lassen sich auf wenige Ebenen reduzieren: Kontrollfluss des Nutzers (NotAllowedError), App-Lifecycle/Concurrency (AbortError), Sicherheitskontext/Konfiguration (SecurityError) oder Options-/Zustandsfehler (InvalidStateError, ConstraintError, DataError). Das weitaus größte Volumen entfällt auf NotAllowedError, was in der Regel ein erwartetes Verhalten ist (Nutzer hat den Prompt geschlossen).
• Wie disambiguiert man NotAllowedError? Verwenden Sie Timing (sofortige Ablehnung vs. Nutzerabbruch vs. Timeout), einen QR/Hybrid-Indikator, Nutzeraktivierungs-Kontext (besonders auf iOS/Safari) und den Operationstyp (Conditional UI vs. modaler Login vs. Passkey-Erstellung vs. Conditional Create). Behandeln Sie nicht alle NotAllowedError als denselben Ausfallgrund.
• Warum ist der Operationstyp wichtig? Derselbe error.name ist während eines Conditional UI Logins ein völlig anderes Signal als während eines Conditional Create oder bei manueller Passkey-Erstellung. Den Operationstyp zusammen mit dem Fehler zu protokollieren, macht aus einem generischen NotAllowedError eine Kategorie, an der man ansetzen kann.
• Welcher Mindestkontext macht Fehler debuggbar? Erfassen Sie error.name, Operationstyp, Time-to-Error, Flow-Typ, ob QR/Hybrid-UI angezeigt wurde, OS/Browser/Gerät (inkl. Versionen), eine Korrelations-ID (auth_flow_id) sowie serverseitige Ablehnungsgründe als explizite Codes.

Zwei Faustregeln gelten für alle Fehlertypen: Zeigen Sie dem Nutzer niemals rohe Browserfehler an – bieten Sie stattdessen immer einen Fallback-Pfad an – und trennen Sie lokale Versuche von QR/Hybrid-Cross-Device-Versuchen, da diese aus unterschiedlichen Gründen fehlschlagen und unterschiedliche Fixes erfordern. Auf großer Skala ist die Pflege der Fehlerklassifizierung über alle Browser, OS-Versionen und Credential-Manager hinweg ständige Arbeit.

Über Corbado

Corbado ist die Authentication Intelligence Platform für CIAM-Teams, die Consumer-Authentifizierung im großen Maßstab betreiben. Wir zeigen Ihnen, was IDP-Logs und generische Analytics-Tools nicht sehen können: welche Geräte, OS-Versionen, Browser und Credential-Manager Passkeys unterstützen, warum Enrollments nicht zu Logins werden, wo der WebAuthn-Flow scheitert und wann ein OS- oder Browser-Update den Login still und leise unterbricht – und das alles, ohne Okta, Auth0, Ping, Cognito oder Ihren In-House-IDP zu ersetzen. Zwei Produkte: Corbado Observe ergänzt Observability für Passkeys und jede andere Login-Methode. Corbado Connect bringt Managed Passkeys mit integrierter Analytics (neben Ihrem IDP). VicRoads betreibt Passkeys für über 5 Mio. Nutzer mit Corbado (+80 % Passkey-Aktivierung). Mit einem Passkey-Experten sprechen →

Im Web fassen Browser beide Fälle aus Datenschutzgründen als NotAllowedError zusammen, daher können Sie sie nicht direkt unterscheiden. Nutzen Sie das Timing als Hilfsmittel: Ein Fehler in unter 1 Sekunde bedeutet meist eine Ablehnung durch die Umgebung oder eine fehlende Funktion, während 1-15 Sekunden darauf hindeuten, dass der Nutzer den Dialog gesehen und geschlossen hat. Bei nativen iOS- und Android-Apps gibt Ihnen das Setzen von preferImmediatelyAvailableCredentials vor der Anfrage ein klares "Keine Anmeldedaten"-Signal (iOS Code 1005, Android GetCredentialRequest), bevor überhaupt eine UI angezeigt wird.

In optimierten, großen Passkey-Implementierungen sind über 95 % der erfassten WebAuthn-Fehler erwartete Nutzerabbrüche, keine Systemausfälle. Das reine Tracking von error.name-Zählungen ohne die Trennung von "Nutzer hat Prompt geschlossen" und echten Fehlschlägen bläht Fehlermetriken auf und verdeckt echte Probleme. Unterteilen Sie Ihre Zählungen nach Operationstyp und behandeln Sie Nutzerabbruch-Kategorien getrennt von unerwarteten Fehlern wie SecurityError, ConstraintError und DataError.

Der iOS-Code 1005 (NotInteractive) bedeutet, dass kein Passkey auf dem Gerät verfügbar war, als preferImmediatelyAvailableCredentials beim ASAuthorizationController gesetzt wurde, und dass dem Nutzer keine UI angezeigt wurde. Dies ist das klare "Kein Passkey existiert auf diesem Gerät"-Signal, das Webbrowser aufgrund von Datenschutzvorgaben nicht bieten können. Klassifizieren Sie immer anhand des numerischen Codes, nicht anhand der localizedDescription, da Apples Nachrichten in über 30 Sprachen übersetzt sind und sich über OS-Versionen hinweg ändern können.

Während eines Conditional Create sind NotAllowedError, AbortError und InvalidStateError allesamt erwartete Ausgänge und sollten stillschweigend ignoriert werden, anstatt sie als Fehler darzustellen. Ein NotAllowedError zeigt an, dass Autofill nicht verfügbar ist oder die Seite den Fokus verloren hat, während ein InvalidStateError bedeutet, dass bereits ein Passkey im Provider existiert. Verwenden Sie vor dem Aufruf getClientCapabilities(), um die conditionalCreate-Unterstützung zu verifizieren, und prüfen Sie den Sichtbarkeitsstatus des Dokuments, um Ihre Fehlerzahlen nicht künstlich aufzublähen.

Erfassen Sie den Operationstyp (Conditional UI, modaler Login, manuelles Create, Conditional Create oder Auto-Append), die Zeit bis zum Fehler seit Start der Operation, OS-Version, Browser-Version, Hardware-Modell, ob eine QR/Hybrid-UI erschien und eine Korrelations-ID, um eine Verbindung zu serverseitigen Logs herzustellen. Fehler bei der Server-Überprüfung wie eine abweichende Challenge, ungültige Signatur und nicht gefundene Credentials sollten als explizite, strukturierte Codes geloggt werden und nicht mit clientseitigen DOMException-Namen vermischt werden. Diese Signale zusammen ermöglichen die Einteilung der großen Mehrheit der Fehler in Kategorien, die ohne Raten behandelt werden können.