Cognito创建用户报错：Alias entry already exists for a different username

错误原因 #

这个错误的核心是你的Cognito用户池配置了某个属性作为登录别名，且该属性的值已被其他用户（包括软删除用户）占用。即使你认为新用户的所有信息都唯一，也可能存在隐性重复（比如邮箱大小写不敏感、软删除用户的遗留别名等）。

排查与解决步骤 #

1. 检查用户池的别名配置 #

• 进入AWS控制台的Cognito用户池，导航到「登录体验」→「登录别名」
• 查看哪些属性被设为登录别名（常见的是email、phone_number、preferred_username）
• 确认这些别名是否开启了「防止重复」开关（开启后，该属性值必须在用户池中全局唯一）

2. 定位重复的别名值 #

• 软删除用户影响：Cognito删除用户后，别名会保留30天，这段时间内无法重复使用。可以在用户池的「用户和组」页面，开启「显示已删除用户」选项，检查是否有占用目标别名的软删除用户
• 隐性重复问题：比如email别名默认不区分大小写，test@example.com和TEST@example.com会被视为同一个别名；或者输入时的空格、特殊字符导致的意外重复
• 未显式设置的别名属性：如果将preferred_username设为别名，但创建用户时未指定该属性，Cognito会默认用username填充，若新用户的username与其他用户的preferred_username重复，也会触发错误

3. 针对性解决 #

• 移除不必要的别名：如果不需要某个属性作为登录别名，直接从「登录别名」列表中移除，即可避免该属性的唯一性约束
• 清理重复别名：对于软删除用户，可以调用admin_delete_userAPI彻底删除（无法恢复），或等待30天自动清理；对于显性重复的属性值，修改新用户的对应属性
• 调整创建逻辑：在调用admin_create_user前，先调用admin_get_user或list_users检查目标别名是否已被占用；创建用户时确保所有别名属性都显式设置唯一值

4. 代码优化建议 #

如果需要保留别名唯一性，可以在代码中添加前置检查逻辑：

def check_user_exists(username, email):
    try:
        # 检查用户名是否存在
        client.admin_get_user(UserPoolId=os.environ.get('COGNITO_POOL_ID'), Username=username)
        return True
    except client.exceptions.UserNotFoundException:
        # 检查邮箱别名是否存在
        response = client.list_users(
            UserPoolId=os.environ.get('COGNITO_POOL_ID'),
            Filter=f"email = \"{email}\""
        )
        return len(response['Users']) > 0

验证 #

在控制台手动创建用户时，确保所有别名属性都填写唯一值，若仍报错，说明问题确实出在用户池配置或已存在的用户数据，而非代码逻辑。

内容的提问来源于stack exchange，提问作者buron