排查常见的 Credential Manager 错误

本指南列出了与 Credential Manager 相关的常见错误代码和说明，并提供了一些有关其原因的信息。

错误代码和说明 原因

android.os.TransactionTooLargeException

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

CreateCredentialCancellationException or GetCredentialCancellationException

通行密钥的注册或检索已被用户取消。

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

CreateCredentialCustomException or GetCredentialCustomException

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

CreateCredentialInterruptedException or GetCredentialInterruptedException

操作可能已中断，因为用户导航到设置以重新配置密码管理器。其他原因也可能导致中断。请尝试再次调用。

CreateCredentialUnknownException

在保存密码期间，从 One Tap 收到密码失败响应 16: [28431] 跳过密码保存，因为用户可能会看到 Android 自动填充的提示。

此错误仅影响 Android 13 及更早版本，并且仅当 Google 是指定的自动填充提供方时才会出现。在这种情况下，用户会收到来自自动填充的保存提示，并且密码将存储在 Google 密码管理器中。重要的是，使用 Google 自动填充保存的凭据与 Credential Manager API 是双向同步的。因此，可以安全地忽略此错误。

CreatePublicKeyCredentialDomException & GetPublicKeyCredentialDomException

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

CreatePublicKeyCredentialDomException & GetPublicKeyCredentialDomException

无法验证传入的请求。

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

CreatePublicKeyCredentialDomException:

注册期间无法创建密钥

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

CreatePublicKeyDomException & GetPublicKeyCredentialDomException

通行密钥注册已被用户取消。

通行密钥检索已被用户取消。

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

GetCredentialProviderConfigurationException & CreateCredentialProviderConfigurationException

getCredentialAsync 未找到提供方依赖项

createCredentialAsync 未找到提供方依赖项

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

GetCredentialUnsupportedException or CreateCredentialUnsupportedException

您的设备不支持 Credential Manager

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

GetPublicKeyCredentialException

无法解密凭据

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

NoCredentialException

未找到匹配的凭据

未在设备上找到匹配的凭据。如果用户之前没有保存任何凭据，这是预期行为。

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

用户需要重置其 Chrome 服务器端数据。这些数据除了已保存的密码和通行密钥外，还包括书签和 Chrome 设置。如需了解 Chrome 存储哪些数据的更多信息，请访问您帐号中的 Chrome 数据。

  1. 转到 chrome.google.com/sync。
  2. 在底部，选择清除数据。
  3. 在设备上，在 Chrome 中开启同步功能。

开始登录失败：8：未知内部错误。

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

无法获取同步帐号

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