CosmosDB容器创建失败：CreateContainerIfNotExistsAsync报Bad Request异常

常见原因及排查步骤 #

1. 分区键路径问题 #

分区键路径必须是合法的JSON路径：

• 确认路径拼写、大小写是否正确（Cosmos DB路径区分大小写，比如/Category和/category是两个不同路径）
• 路径不能包含特殊字符（如空格、$、?等），你的代码中/category格式合法，但需确保业务逻辑中该属性符合要求

2. 容器ID违反命名规则 #

Cosmos DB容器ID有严格限制：

• 长度需在1-255字符之间
• 不能包含/ \ # ?或尾部空格
  你的代码中ToDoList看似合规，但实际排查时要确认是否存在隐藏字符或拼写错误

3. 吞吐量配置不匹配 #

• 如果你的数据库是服务器less模式，不能指定固定吞吐量参数，需移除throughput: 100，使用默认配置。服务器less容器不支持手动设置RU值，强行指定会触发Bad Request
• 标准容器最小吞吐量是100RU，你的配置在此场景下合法，但需确认数据库模式

4. 权限与密钥验证 #

虽然容器已存在时能正常执行，但仍需检查：

• 使用的密钥是否具备创建容器的权限（主密钥默认拥有该权限，资源令牌需确保包含Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/write权限）
• 密钥是否存在复制错误（如多余空格、字符缺失）

5. SDK版本兼容性 #

旧版本Microsoft.Azure.Cosmos SDK可能存在方法逻辑缺陷，建议升级至最新稳定版（v3.x系列），避免已知bug导致的异常

6. 资源名称大小写冲突 #

Cosmos DB的数据库、容器名称区分大小写，比如代码中创建的TestDB若与实际存在的数据库名称（如testdb）大小写不一致，可能引发上下文异常，需确认数据库实际名称与代码匹配

7. 捕获异常详情定位问题 #

添加异常捕获，查看CosmosException的具体信息，能快速定位根因：

try
{
    Container container = await database.CreateContainerIfNotExistsAsync(
        id: "ToDoList",
        partitionKeyPath: "/category",
        throughput: 100
    );
}
catch (CosmosException ex)
{
    Console.WriteLine($"状态码: {ex.StatusCode}, 子状态码: {ex.SubStatusCode}, 错误消息: {ex.Message}");
}

比如子状态码会明确提示是分区键无效、吞吐量不支持还是命名违规等具体问题

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