MongoDB 查询如果在执行前返回错误码 2400，通常意味着服务端在查询计划校验阶段已经拒绝了当前请求。它不一定代表索引损坏或数据丢失，而是 hint 指定的索引无法满足查询要求。更准确地说，hint 是一种强约束，它告诉查询优化器只能选择某个索引；当这个约束与集合上实际存在的索引不匹配时，MongoDB 不会回退到全表扫描，而是直接抛出错误。这与普通查询中优化器自动选择索引的行为有本质区别。
一、错误码2400的机制：hint失败发生在查询规划阶段
在 MongoDB 的查询执行流程中，请求首先会经过解析、查询计划生成、索引选择这几个阶段。正常情况下，查询优化器会根据集合的统计信息、候选索引数量以及查询条件，自动选择一个成本最低的执行计划。hint 的作用就是跳过这种自动选择，直接指定一个索引名或索引 key pattern，让优化器必须按照这个约束执行。
当 hint 指定的索引不存在、拼写有误、被隐藏，或者指定的索引 key pattern 与查询条件不兼容时，查询规划阶段就会抛出错误。此时错误码 2400 往往伴随着 planner returned error 或 unable to find index for hint 之类的信息。需要注意的是，这种错误发生在执行计划生成之前，并不会返回查询结果，也不会回退到集合扫描。
也就是说，hint 失败属于典型的强制约束失败。开发者在日志里看到 2400 时，不应该先怀疑数据写入、复制延迟或连接池问题，而应当优先检查 hint 参数本身是否仍然有效。
二、定位2400：四个最容易被忽略的触发点
造成 hint 使用不当的原因通常集中在索引对象本身。第一个常见原因是索引名写错。很多人创建索引时自定义了名称，但调用 hint 时却使用了字段名，或者反过来，创建时没有指定 name，查询时又误填了一个并不存在的索引名。例如订单表上创建了 idx_status_created，代码里却写成了 hint("idx_status")，就会直接触发错误。
第二个原因是索引被隐藏。MongoDB 支持将索引设置为 hidden 状态，隐藏后的索引不再被查询优化器自动使用，也不会被 hint 强制使用。即使 db.orders.getIndexes() 能看到它，hint 依然会失败。第三个原因是 hint 使用了 key pattern，但字段顺序、排序方向与实际索引不一致。比如索引是 { status: 1, created_at: -1 }，但 hint 写成了 { created_at: -1, status: 1 }，虽然字段相同，但 pattern 不同，规划阶段同样会拒绝。
第四个原因是分片集群场景下的限制。在分片集合中，如果查询没有包含分片键，或者 hint 指定的索引不是以分片键作为前缀，mongos 路由层可能会直接返回错误码 2400。此时问题不在单个分片，而在路由层对索引约束的校验。
| 常见原因 | 典型错误写法 | 修复方式 |
|---|---|---|
| 索引名拼写错误 | hint("idx_status") | 使用 getIndexes 确认真实索引名 |
| 索引被隐藏 | 创建 hidden: true 后继续 hint | 取消隐藏或改走其他索引 |
| key pattern 不匹配 | 顺序或排序方向不对 | 完全复制创建索引时的 key pattern |
| 分片键约束不满足 | hint 索引未以分片键为前缀 | 重新设计索引或让查询包含分片键 |
三、从错误到修复：正确使用 hint 的完整示例
假设有一个订单集合 orders，常见的查询条件是按照订单状态 status 过滤，并且根据创建时间 created_at 倒序排列。为了加速查询，可以创建如下的复合索引：
// 创建订单集合索引
db.orders.createIndex(
{ status: 1, created_at: -1 },
{ name: "idx_status_created" }
);
如果代码中使用了不存在的索引名，就会在规划阶段报出 2400。下面这种写法就是典型的错误用法：
// 错误：hint 使用不存在的索引名
db.orders.find({ status: "PAID" })
.hint("idx_status")
.toArray();
// 可能返回：planner returned error ... hint provided does not correspond to an existing index
正确的做法是先调用 getIndexes 查看集合上所有索引，确认索引名称和 key pattern 都准确无误，然后再使用 hint。建议同时使用 explain 查看执行计划，确认查询确实走了目标索引，而不是其他候选索引。
// 先确认现有索引
db.orders.getIndexes();
// 使用正确索引名强制走索引，并查看执行计划
db.orders.find({ status: "PAID" })
.hint("idx_status_created")
.explain("executionStats");
从 explain 输出的 winningPlan 中可以查看 inputStage 的 indexName 字段，确认当前查询使用的是 idx_status_created。如果没有出现 2400，但执行计划却走了 COLLSCAN，那说明 hint 没有生效，或者你连接的 MongoDB 版本对 hint 的支持存在差异，需要继续检查驱动与服务器版本。
对于隐藏索引，即使名称正确，hint 也会失败。下面示例演示了隐藏索引对 hint 的影响：
db.orders.createIndex(
{ user_id: 1 },
{ name: "idx_user_id_hidden", hidden: true }
);
// 即使索引存在，也会因为 hidden 属性导致 hint 失败
db.orders.find({ user_id: 8888 }).hint("idx_user_id_hidden");
如果业务确实需要使用某个索引，但又不想把它从隐藏状态恢复，可以先确认隐藏索引是否还有维护成本，再决定是否使用 collMod 命令取消 hidden 属性。修复方式如下：
db.runCommand({
collMod: "orders",
index: {
keyPattern: { user_id: 1 },
hidden: false
}
});
四、生产环境中如何减少 hint 误用带来的故障
强制索引是一把双刃剑。它在一些极端场景下可以稳定执行计划、规避糟糕的索引选择，但也让查询失去了优化器的保护。一旦索引被删除、重命名、隐藏，或者分片集群重新平衡导致索引在不同分片上的状态不一致，原本正常的请求会突然开始报 2400。因此，生产环境中应当尽量限制业务代码里直接写 hint 的范围。
更稳妥的做法是让查询优化器自动选择索引，同时通过索引过滤器来纠正执行计划。索引过滤器可以针对特定查询形状绑定推荐索引，而不需要应用代码把索引名写死。例如针对 status 等于 PAID 的查询固定使用 idx_status_created，可以执行：
db.runCommand({
planCacheSetFilter: "orders",
query: { status: "PAID" },
indexes: ["idx_status_created"]
});
索引过滤器虽然也有维护成本，但它至少把索引选择策略放在数据库侧统一管理，比分散在各个服务里的 hint 更容易治理。同时，DBA 在删除或重建索引前，也应该先审计应用代码、慢查询日志和运行中的操作，确认没有请求依赖即将变更的索引。
针对分片集群，最好在设计组合索引时就把分片键作为前缀。如果查询必须使用 hint，那么要确保 hint 索引满足分片键前缀要求，并且查询条件里包含分片键等值或范围条件。否则即便单分片上能创建索引，路由层也可能在规划阶段拒绝请求，表现为 2400。
最后，无论使用 hint 还是索引过滤器，都应当定期使用 explain("executionStats") 检查执行计划的 totalKeysExamined、totalDocsExamined 和 executionTimeMillis。只有持续验证，才能确认强制索引确实带来了预期的收益，而不是在错误码出现后才被动排查。
MongoDB hint错误码2400强制索引修改时间：2026-08-24 00:18:14