使用.NET Cosmos DB SDK读取单文档时遭遇404 NotFound错误排查

一、通过错误子状态码区分缺失资源 #

Cosmos DB的404错误可以通过**子状态码（Substatus）**快速判断缺失的资源类型：

• 子状态码0：一般对应数据库或容器不存在
• 子状态码1002：明确表示目标文档不存在

你给出的错误中子状态码是0，但你已通过门户确认容器存在，那问题大概率出在代码逻辑或参数匹配上——比如容器实例不匹配、分区键类型错误，这些情况也可能返回子状态码0的404。

二、排查代码中的关键问题 #

1. 全局容器实例可能不匹配目标集合 #

你的类中使用了全局变量_container，但GetDocument方法会传入不同的collectionId调用GetContainer。如果GetContainer的逻辑是仅当_container为null时才创建，那么当你多次调用不同集合的GetDocument时，_container会被之前的容器实例覆盖，导致后续请求用错容器，触发404。

解决方式：不要用全局容器变量，改为根据collectionId动态获取对应容器；或者在GetContainer中检查当前_container的名称是否与传入的collectionId匹配，不匹配则重新创建。

2. 分区键类型不匹配 #

你明确categoryId是文档的int类型属性，分区键为/categoryId，但代码中却将categoryId转为字符串传入PartitionKey：

partitionKey: new PartitionKey(categoryId.ToString())

Cosmos DB的分区键是类型严格敏感的，int类型的123和字符串类型的"123"属于完全不同的分区键值，会直接导致无法定位到目标文档，返回404。

解决方式：直接用int类型的categoryId创建PartitionKey（SDK支持int重载）：

partitionKey: new PartitionKey(categoryId)

3. 文档ID大小写不匹配 #

Cosmos DB的文档ID是大小写敏感的，比如"Order123"和"order123"会被视为两个不同的文档。确认你传入的id与门户中显示的文档ID完全一致（包括大小写）。

4. 捕获更精准的错误信息 #

不要捕获通用的Exception，改为捕获CosmosException，它能提供更详细的错误维度：

catch(CosmosException e)
{
    throw new Exception($"Cosmos错误: {e.StatusCode}, 子状态码: {e.SubStatusCode}, 详情: {e.ErrorMessage}");
}

三、快速验证步骤 #

1. 调试时查看_container的Uri属性，确认它指向门户中的目标容器。
2. 在门户中查看目标文档的categoryId类型，确保代码传入的分区键类型与之完全一致。
3. 直接复制门户中文档的ID传入GetDocument，排除ID拼写或大小写问题。

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