Cognito用户注册未抛出UsernameExistsException问题排查

• 邮箱未配置为唯一用户属性
  Cognito默认不会强制邮箱属性的唯一性，即使你将邮箱作为用户属性使用。你需要在用户池的属性配置中，将邮箱标记为唯一：

  • 控制台操作：进入用户池 -> 常规设置 -> 属性 -> 找到邮箱属性，勾选“唯一”选项。
  • CDK配置：在UserPool的schema属性中，为邮箱属性设置unique: true，示例：

    new cognito.UserPool(this, 'MyUserPool', {
      // 其他配置
      schema: [
        {
          attributeDataType: cognito.AttributeDataType.STRING,
          name: 'email',
          required: true,
          unique: true, // 关键配置
        },
      ],
      preventUserExistenceErrors: false,
    });
    

• PreventUserExistenceErrors配置未生效
  确认你的用户池实际配置是否已更新为LEGACY模式：

  • 登录AWS控制台，进入目标用户池 -> 应用集成 -> 应用客户端设置 -> 查看“防止用户存在错误”选项是否为“遗留（LEGACY）”。
  • 若使用CDK/CloudFormation部署，检查部署日志是否无报错，确保配置已成功应用到用户池。

• 自定义注册触发器干扰了原生校验
  如果你的用户池配置了pre-signup Lambda触发器，需要确认触发器逻辑是否绕过了Cognito的唯一性检查：

  • 检查pre-signup触发器代码，若返回了event.response.autoConfirmUser = true或其他允许注册的操作，可能会跳过Cognito原生的邮箱唯一性校验，导致不会抛出UsernameExistsException。
  • 临时禁用pre-signup触发器，重新测试注册流程，看是否能正常触发错误。

• 注册请求未正确传递邮箱属性
  确认调用Cognito的SignUp API时，是否正确将邮箱放入UserAttributes参数中，且属性名严格为email（小写）：

  • 错误示例：使用Email作为属性名，或未在UserAttributes中包含邮箱。
  • 正确请求格式（以AWS SDK v3为例）：

    import { CognitoIdentityProviderClient, SignUpCommand } from "@aws-sdk/client-cognito-identity-provider";
    
    const client = new CognitoIdentityProviderClient({});
    const command = new SignUpCommand({
      ClientId: "YOUR_CLIENT_ID",
      Username: "USERNAME", // 若用户名与邮箱一致，这里也需填邮箱
      Password: "PASSWORD",
      UserAttributes: [{ Name: "email", Value: "user@example.com" }],
    });
    

• 已存在用户的状态异常
  检查已存在的用户状态是否为已启用，若用户处于已删除或已禁用状态，部分场景下Cognito可能不会触发UsernameExistsException。可通过用户池的“用户和组”页面查看目标用户的状态。

内容的提问来源于stack exchange，提问作者luca.p.alexandru