Skip to main content

Troubleshooting

The troubleshooting content in this section is intended to help organizations proactively become aware of and address potential issues with implementations of support for passkeys.

The passkey ecosystem

For passkeys to function properly, six entities must work together. FIDO Alliance member companies from around the world, along with the W3C, have created industry standards to help ensure these entities work well together.

  • A relying party (typically a website)
  • Operating systems
  • Browsers
  • Credential managers
  • Hardware
  • End user

""

These six entities work together to make passkeys secure and easy to use. When issues arise it is often due to combinations of these entities behaving in unexpected ways.

As you become familiar with the common troubleshooting optics, you should also become familiar with which of the six entities might be contributing to the issue. You can use this knowledge to inform the design of your passkey roll-out strategy and to make issues easier to troubleshoot.

note

The term relying party is used in specifications for identity and access management standards. At a technical level, a relying party is a server providing access to a secured software application. It is abbreviated as RP.

The FIDO-Dev community group and Passkeys Developer discussions

The FIDO-dev community group, is a free resource you can use to ask questions and get answers. This resource is used by organizations from around the world to discuss the latest updates, features, and issues within the passkey ecosystem. Developers, designers, product managers, and architects post questions or issues and receive quick replies from peers and people at the global companies that originated the standards that power passkeys.

The Passkeys Developer discussions is also a great resource for developers to ask questions about functionality and behaviors, as well as showcase their own solutions.

Resolution types

There are three possible outcomes for troubleshooting items found on these pages:

  • Resolved: Resolutions are in the control of relying parties and can be implemented immediately.
  • Pending resolutions: Pending resolutions can only be resolved with the introduction of a new industry standard. The industry standard must then be implemented by browsers, operating systems, credential providers, or hardware providers. The FIDO Alliance lists pending resolutions when a standard is actively pursued in the ecosystem and there is information about the standard available to the general public. This process often starts with an explainer that is available publicly on GitHub. For example, the WebAuthn Conditional Registration Extension is an explainer. This particular explainer is dated August 2023 and the functionality described in the explainer is now available in iOS version 18. Other operating systems and credential managers will likely also implement the functionality described in the explainer.
  • No current resolution: Items with no current resolution can be mitigated but not fully resolved. In these cases, the FIDO Alliance believes it is important and helpful to describe the item, even when the root cause can not be resolved by the relying party. This transparency helps organizations proactively plan for potential edge case issues.

Troubleshooting known items

Before exploring troubleshooting items in detail, it is helpful to become familiar with common themes. Read the overviews first, then use the links to explore the detail pages for each item if needed.

Internal note
  • The intention is that each section also has a dedicated page. Linked items take the reader to that page.
  • This Troubleshooting page is one of the higher priority outcomes from Phase 1 research with RPs.
  • This Troubleshooting page largely focusses on user experience issues. In 2025 it should be grown to include the most common technical troubleshooting as well.

Troubleshoot Cross-Device Sign-In and Transport

  • User misunderstanding of recognized devices might create privacy concerns
  • Some people might not have success with cross-device sign-in

Troubleshoot Education for End Users

  • Educate people on what to do if their device is lost or stolen
  • How multiple passkeys work with a single account might create confusion
  • Passkeys managed by some credential providers are not available on all operating systems
  • Some people believe, incorrectly, that biometrics are sent to the relying party
  • Use of near-field communication (NFC) might be unfamiliar

Troubleshoot Ecosystem Inconsistencies

  • Breaking changes in the ecosystem can block passkey use
  • Inconsistent experience across the ecosystem might create confusion
  • It is impractical or impossible to test all ecosystem combinations
  • It is impractical to show all ecosystem combinations in Help resources
  • Sign in terminology used for payment confirmation might create confusion
  • Passkey sharing is only allowed by some credential managers
  • Some people cannot use passkeys at work due to blocked access
  • Using multiple credential providers might create confusion

Troubleshoot Passkey Management and Removing Passkeys

  • Access to passkeys after death or serious injury
  • Removing passkeys from the relying party can create multiple issues
  • Security key protocols might limit the number of accounts they can be associated with
  • Technical implementation of design guidelines is not documented

Troubleshoot User Interfaces for Sign-In

  • Create a single user interface for synced and device-bound passkeys
  • Disabling autofill can lead to issues
  • Sign in with a passkey buttons might lead to challenges

Troubleshoot When the WebAuthn Ceremony Fails

  • Failed WebAuthn ceremonies might create confusion

  • Failed WebAuthn ceremonies might create confusion