排查 Credential Manager 的常见错误

android.os.TransactionTooLargeException

这是由一个已知问题导致的，即当设备上存在多个 Google 账号时，Android 14 及更高版本上的 credentialManager.getCredential() API 无法显示登录对话框。此问题仅在 GetGoogleIdOption 中出现，而不会在 GetSignInWithGoogleOption 中出现。此问题已在 Google Play 服务版本 24.40.XX 及更高版本中得到修复。

CreateCredentialCancellationException

用户取消了通行密钥注册或检索。

用户已选择不创建或使用凭据。现在，您可以调整界面以提供替代登录方法，也可以继续执行流程中的后续步骤。

GetCredentialCancellationException

由于未获得必要的用户授权，凭据检索流程已终止。虽然这种情况最常发生在用户手动取消登录流程时，但也可能表示由于技术限制，请求未获授权。由于此错误表示缺少同意情况，因此请勿自动重试请求，因为这会造成干扰性的用户体验。不过，开发者应监控此异常的发生频率。大量“取消”可能实际上表明存在配置错误（例如缺少或错误的范围），导致授权界面无法成功完成。如果您发现意外趋势，请检查您的请求参数和 [Relying Party][2] 配置。

注意：错误消息可能会因凭据类型而异：

• 对于通行密钥，错误消息可能是“用户取消了通行密钥注册或检索”。
• 对于“使用 Google 账号登录”，错误消息可能是“Activity is cancelled by the user”（用户取消了 activity）。

CreateCredentialCustomException 或 GetCredentialCustomException

使用第三方 SDK 通过子类化 CreateCustomCredentialRequest 或 GetCustomCredentialOption 的请求对象进行 API 调用时，您可能会遇到错误。如果发生这种情况，请检查 SDK 中是否有与 e.type 匹配的自定义异常类型常量。如果未找到匹配项，则可以安全地舍弃或记录异常。

CreateCredentialInterruptedException 或 GetCredentialInterruptedException

该操作可能已被中断，因为用户前往设置重新配置了密码管理器。其他原因也可能导致了中断。请重新尝试通话。

CreateCredentialUnknownException

保存密码期间，点按一下即可找到密码失败响应 16：[28431] Android 自动填充功能可能会提示用户，因此跳过密码保存。

当 Google 是指定的自动填充提供程序时，此错误仅影响 Android 13 及更低版本。在这种情况下，用户会收到自动填充功能发出的保存提示，并且密码会存储在 Google 密码管理工具中。请务必注意，使用 Google 自动填充功能保存的凭据会与 Credential Manager API 进行双向同步。因此，您可以放心地忽略此错误。

CreatePublicKeyCredentialDomException 和 GetPublicKeyCredentialDomException

DOM 异常可能包含更具体的 domError。您可以将其映射到 WebAuthn DomException，以了解更多详情。

CreatePublicKeyCredentialDomException 和 GetPublicKeyCredentialDomException

无法验证传入请求。

密码管理器的服务器无法识别应用的软件包 ID。这表明您的服务器端集成可能存在问题，尤其是数字资产链接设置。仔细检查资源链接文件中的软件包 ID 和 SHA 是否准确无误。

CreatePublicKeyCredentialDomException：

注册期间无法创建密钥

当用户在注册期间关闭屏幕锁定对话框时，可能会出现此问题。

CreateCredentialNoCreateOptionException

此特定异常表示用户未配置有效的密码管理器。此错误不是用户启动的手动取消流程，而是单独的故障。

CreatePublicKeyDomException 和 GetPublicKeyCredentialDomException

用户取消了通行密钥注册。

用户取消了通行密钥检索。

当用户在注册 / 检索通行密钥期间关闭指纹对话框时，可能会出现此问题。

GetCredentialProviderConfigurationException 和 CreateCredentialProviderConfigurationException

未找到 getCredentialAsync 的提供方依赖项

找不到 createCredentialAsync 的提供程序依赖项

缺少 androidx.credentials:credentials-play-services-auth:<latest-version> 依赖项。

GetCredentialUnsupportedException 或 CreateCredentialUnsupportedException

您的设备不支持凭据管理器

确保您的凭据库已更新到 1.2.1 版或更高版本。

GetPublicKeyCredentialException

未能解密凭据

在退出并重新登录 Google 账号后尝试使用通行密钥时，会出现此问题。指示用户在设备上重新登录其 Google 账号。

NoCreateOptionException

如果用户未在其设备上设置任何通行密钥凭据，或者未配置密码管理器，则此异常属于预期行为。

NoCredentialException

找不到匹配的凭据

此异常会在以下情况下发生：

• 在设备上没有已获授权的账号的情况下，setFilterByAuthorizedAccounts 设置为 true。
• 设备上没有已登录的账号（未添加任何账号或账号需要重新进行身份验证）。
• 如果设备上任何账号的登录提示处于停用状态，系统就不会显示底部操作界面。此全局设置位于 Google 账号设置 > 使用 Google 账号登录下，必须启用此设置，底部操作表界面才能针对任何账号显示。这不会影响按钮流程。

由于加密数据被锁定，无法创建通行密钥

用户需要重置 Chrome 服务器端数据。这些数据包括书签、Chrome 设置以及已保存的密码和通行密钥。如需详细了解 Chrome 会存储哪些数据，请前往您账号中的 Chrome 数据页面。

1. 前往 chrome.google.com/sync。
2. 选择底部的清除数据。
3. 在该设备上开启 Chrome 同步功能。

On Begin Sign In Failure: 8：未知内部错误。

设备可能未正确设置 Google 账号。通行密钥 JSON 的创建方式可能存在问题。仔细检查实现是否准确无误。

无法获取同步账号

Google Play 服务版本 24.40.XX 及更高版本将提供更具信息性的错误代码。例如，调用方现在会收到取消错误消息，而不是“无法获取同步账号”。