Messaging Guidelines for Passkey Failure States
Passkey errors are a moment of friction. Your messaging in these moments can either preserve trust and momentum or increase drop-off and doubt. Research shows that clear, empathetic, and actionable communication makes a meaningful difference in how users interpret and respond to failure.
Messaging principles
The principles help ensure that users feel supported, not stuck. Each principle is grounded in user research and is designed to minimize confusion, reduce self-blame, and keep users moving forward with confidence.
These principles apply across all failure types.
Tell users what happened, even if you don’t know exactly
Users expect transparency and clarity, even in the absence of detailed technical diagnostics. Vague messages such as Something went wrong increase uncertainty and may lead users to assume personal fault or abandon the task. What to do: Offer a concise and understandable description of what likely occurred, using plain language. If the precise cause is unknown, acknowledge common reasons (for example, connectivity, device settings, or temporary issues) without resorting to overly technical terms.
Clarify who needs to act and when
Users frequently report uncertainty regarding whether they are expected to act or if the system will resolve the issue automatically. Ambiguous phrases such as We’ll try again later fail to provide a sense of direction or control.
What to do: Tell the user exactly who’s doing what and when. Use time markers if relevant (in a few seconds) or clear calls to action if it’s up to them.
Use supportive, blame-free language
Passkey failures often evoke self-blame, especially among users unfamiliar with the technology. Language that implies fault or highlights failure can erode trust and increase frustration.
What to do: Use empathetic and neutral phrasing that reassures users the issue may be system-related or easily resolved.
Provide multiple, clearly labeled paths
Users should not encounter an error message that leaves them uncertain about how to proceed. A message without a clear next step represents a dead end and increases the likelihood of abandonment.
What to do: Provide users with at least one actionable next step, ideally more. Label buttons and links clearly, reflecting the intended outcome (for example, retry, alternate sign-in method, or access to support resources).
Design for different user needs and context
Users engage with authentication flows in various contexts, some are in a hurry, some are exploring new technology, and others are attempting to troubleshoot. A one-size-fits-all response may not meet all user needs.
What to do: Provide options that support a range of user goals and scenarios:
- Expedient fallback for those in a hurry
- Troubleshooting support for users seeking resolution
- Educational links for users unfamiliar with passkeys or those wanting to learn more
Ensure that actions are clearly grouped and visually distinct to support decision-making.
Be consistent in layout, labeling, and language
Inconsistent messaging patterns can undermine user comprehension and confidence. Consistency in message structure and terminology supports recognition and learnability, particularly during repeated interactions.
What to do: Standardize the presentation of error messages by maintaining a familiar structure:
- Title or header: short, specific label
- Brief explanation: description of what happened
- Recommended actions: clearly labeled buttons or links
- Optional support: contextual help or learn-more links
Use consistent terminology across all messages (for example, always use Try again instead of alternating between Retry, Refresh, or Resend).
Message Template Structure (General Guidance)
Each passkey failure message should contain these components:
| Component | Purpose |
|---|---|
| Title/header | Short, direct label to help users quickly identify the nature of the error. |
| Brief explanation of what happened | Offers a short, plain-language description of the likely cause of the issue. While not necessarily technical in detail, it should help orient the user and reduce ambiguity. |
| Next step guidance | Clearly communicates what the user should do next and whether the system will take any action on their behalf. This eliminates uncertainty and supports timely resolution. |
| Actions | Presents one or more clearly labeled buttons that reflect immediate paths forward (for example, retry, alternative methods, recovery flows). These enable user agency and reduce frustration. |
| Support | Provides access to additional context or help documentation for users who wish to understand the issue in greater depth or explore long-term solutions. |
| Reassurance (optional) | A brief, empathetic message that acknowledges the inconvenience and reinforces that resolution is achievable. This can help reduce user stress and abandonment. |
Where possible, ensure the visual hierarchy of these elements is consistent across your interface. Headings should be prominent, body copy should be succinct, and action buttons should be visually distinct and logically grouped based on user intent.
Sample Messaging by Error Type
Passkey creation failure
This error occurs during the initial setup of a passkey. It is typically caused by a system-level issue such as a temporary server problem, network disruption, or device configuration conflict. Importantly, it is not the result of user action or error.
| Component | Purpose |
|---|---|
| Title/header | We couldn’t create your passkey |
| Brief explanation of what happened | This appears to be a temporary issue on our side, not caused by anything you did. It may be related to a connection or system error. |
| Next step guidance | You can try again now, or choose to continue without creating a passkey. |
| Actions |
|
| Support | Learn more about passkeys. |
General sign-in failure
This error occurs when a user attempts to sign in using a passkey and the system fails to complete the process. The failure may stem from biometric sensor timeouts, connectivity loss, or system-side interruptions.
| Component | Purpose |
|---|---|
| Title/header | We couldn’t sign you in |
| Brief explanation of what happened | This was likely caused by a system issue, such as a temporary connection error or timeout. |
| Next step guidance | You can try again, or sign in another way if this issue continues. |
| Actions |
|
| Support | Learn more about passkeys |
Invalid passkey failure
This error occurs when a passkey the user attempts to use is no longer recognized by the system. This can happen if the passkey has been deleted, the device was reset, or security settings have changed.
| Component | Purpose |
|---|---|
| Title/header | This passkey is no longer valid |
| Brief explanation of what happened | This can happen if the passkey was deleted, the device was reset, or your account settings changed. It’s not something you did wrong. |
| Next step guidance | You can continue by signing in another way or setting up a new passkey. |
| Actions |
|
| Support | Learn how to manage your passkeys. |
Cross-device Bluetooth failure
This error occurs when a user tries to sign in using a passkey stored on another device, but the two devices fail to connect. Common causes include Bluetooth being disabled on one or both devices or the devices being too far apart.
| Component | Purpose |
|---|---|
| Title/header | We couldn’t connect to your other device |
| Brief explanation of what happened | This may happen if Bluetooth is off or your devices are not close enough to each other. |
| Next step guidance | Turn on Bluetooth on both devices and make sure they’re nearby, then try again or choose another way to sign in. |
| Actions |
|
| Support | Learn more about how to use passkeys across devices. |
UX Research
User experience research revealed that participants found that failure messages during passkey creation and sign-in play a critical role in tryst, clarity, and user agency. Participants consistently emphasized the importance of clear explanation, supportive tone, and actionable next steps.
The user research indicated that vague error messages caused participants to question the credibility of the experience and their role in the error. Participants expressed a strong preference for light diagnostic information, such as mentioning likely causes like connectivity issues, without requiring deep technical explanations. This approach helps participants feel included in the recovery process and reduces feelings of helplessness or exclusion.
“Let me know what the next step is rather than the wording we'll try again later. How are they going to try again later? Is it going to be when I log in or are they just going to try to initiate it on my own? How would I be alerted that it worked or didn't work?.”
— Research 2025 Phase 2 – Participant 6
Participants wanted to know who would take the next step (themselves or the system) and when. Phrases like we’ll try again later left users unsure if they should act immediately or simply wait, leading to unnecessary hesitation or unnecessary troubleshooting.
Participants positively perceived messages that framed errors as temporary, offered immediate retry options, and provided easy pathways to troubleshooting resources. When given actionable options and reassurance, users felt more confident and were more likely to recover successfully from failure states without losing trust in passkeys.
“I like that there's an article, Learn How to Manage Your Passkeys to show me where to go because I would definitely split my screen, have the instructions on one side, and go through it on the other end to make sure I can fix that.”
—Research 2025 Phase 2 – Participant 7
Participants also emphasized the importance of the tone and layout of failure messages. Language that gently guided users, such as suggesting they check device proximity or Bluetooth settings, was seen as more supportive and actionable than overly technical or cold phrasing. Providing retry instructions and offering a fallback option, like Try another way, gave participants a sense of safety and control.
“The language is a lot more conducive to become friction free and reassure the user, where the other one leaves you a little bit with the you're on your own. What do you want to do? Pick your own adventure. I think the right one just tells you, hey, here's some things that we can do.”
— Research 2025 Phase 2 – Participant 8
Notes and next steps
Clear, supportive error messaging is a critical component of delivering a trustworthy passkey experience. When failures occur, users are often unsure of what happened and what to do next. Well-crafted messages reduce confusion, mitigate blame, and increase recovery, helping users stay engaged and confident in using passkeys.
We encourage consistency in tone, structure, and guidance across all failure states. The examples and principles in this page are intended to serve as a foundation for designing and localizing user-centered, resilient messaging.
Next Steps
- Review error message patterns in your current authentication flow.
- Use these templates and principles as a starting point for product and UX copy reviews.
- Run usability tests with real users to validate message clarity and recovery behavior.
- Coordinate across product, engineering, and support teams to ensure alignment.
