1. Java 查询 MongoDB 报 -5 的真实场景与游标机制

com.mongodb.MongoCursorNotFoundException: Query failed with error code -5这个报错，本质是 MongoDB 服务端告诉你：你手里这个游标 ID 已经失效了，别再拿它来取下一批数据。它跟网络断没断、Key 对不对没有直接关系，而是游标在服务端被回收了。理解这一点，排查方向才不会跑偏。

MongoDB 的find()返回的并不是全部结果，而是一个游标对象。驱动第一次向服务端要数据时，默认取 101 个文档或 1MB（谁先到算谁），之后每批取 4MB。同时，服务端给游标设了一个默认 10 分钟的空闲超时：只要 10 分钟内没有任何针对该游标的操作，服务端就会把它清理掉。等你处理完手头这批、再拿同一个游标 ID 去要下一批时，服务端已经查无此游标，于是抛出 -5。

这个场景在 Java 应用里特别常见，因为 Java 侧的处理逻辑往往比取数慢得多。比如你查出一批文档后，对每条记录再发起一次子查询、写文件、调外部接口，单条耗时几十毫秒，一批 500 条就是十几秒甚至更久。如果业务逻辑里还有阻塞、重试、慢 SQL，10 分钟很容易被撑爆。另一个高频诱因是游标被跨线程或跨请求持有：把MongoCursor塞进缓存、放进异步任务，等真正遍历时早就过期了。

还有一种容易被忽略的情况：连接配置本身不稳定导致游标会话中断。比如连接串里没配好超时、连接池被打满、或者请求经过了一层统一网关，网关侧的空闲超时比 MongoDB 的游标超时更短，连接先被掐断，游标自然也就废了。这也是为什么很多团队在把数据库访问收敛到统一 API 通道后，-5 的排查要同时看两段链路：Java 到网关、网关到 MongoDB。

所以排查 -5 的核心思路是两条线并行：一条线确认游标生命周期有没有被业务逻辑拖过 10 分钟，另一条线确认连接与会话有没有在中途被切断。下面先讲清楚统一通道这一侧的配置，再回到游标本身的复现与定位。

2. TaoToken 统一 Key 与 API 通道的前置配置

把 MongoDB 访问相关的模型调用、Agent 编排、代码辅助统一走 TaoToken 之后，Java 应用侧的网络出口会收敛到一个稳定入口，排查 -5 时就能把「连接被中途切断」这个变量先固定下来。TaoToken 提供统一的 Key 和 API 通道，官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api 。

需要先说明边界：TaoToken 是模型与 API 通道的统一入口，不是 MongoDB 数据库本身。你的 MongoDB 连接串仍然指向你自己的数据库实例，TaoToken 负责的是应用里那些模型调用、代码生成、Agent 任务的出口统一。把这两件事分清楚，才不会把 -5 误判成 Key 问题。

前置准备分三步。第一步，在控制台创建 API Key，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，创建后立刻复制保存，页面刷新后不再完整显示。第二步，确认你要用的模型 ID，可以在模型对话页 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 里查看当前可用的模型列表，把 Model ID 记下来。第三步，如果你用 Claude Code 这类编码工具，参考接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 里的 Base URL 写法，避免路径拼错。

这里有个我踩过的坑：很多人把 Base URL 写成https://taotoken.net/api/v1或漏掉/api，结果请求 404，然后误以为是 Key 失效。正确做法是 Base URL 用https://taotoken.net/api，具体路径由客户端 SDK 自己拼接。Key 的传递方式是Authorization: Bearer <你的Key>，注意 Bearer 和 Key 之间有一个空格。

配置完成后，建议先用一次最小请求验证通道是否通，再回到 Java 侧排查 -5。这样能把「通道不通」和「游标过期」两类问题彻底分开，不至于在一个报错上反复绕圈。

3. 可复制的连接参数与游标配置片段

这一节给可直接粘贴的配置。先看统一通道侧的 JSON 配置，适用于大多数支持 OpenAI 兼容协议的工具，路径和字段名保持原样：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoTokenKey", "model": "你的ModelID", "timeout": 60, "max_retries": 2 }

如果你用的是 TOML 风格的配置（比如某些 CLI 工具），等价写法如下：

[provider] base_url = "https://taotoken.net/api" api_key = "sk-你的TaoTokenKey" model = "你的ModelID" timeout = 60

三件套必须齐全：Base URL、Key、Model ID。缺任何一个都会报鉴权或模型不存在，而不是 -5。把这三件套确认无误后，再来看 MongoDB 侧的游标配置。

Java 驱动里控制游标行为的核心是batchSize和noCursorTimeout。下面这段是修正后的查询写法，重点是显式设置批次大小，让每批数据能在超时窗口内处理完：

MongoCollection<Document> coll = mongodb.getCollection(dbName, "files"); BasicDBObject qCondition = new BasicDBObject(); qCondition.put("createdTime", new BasicDBObject("$gte", startTime)); // 显式设置批次大小，避免单批过大导致处理超时 FindIterable<Document> iterable = coll.find(qCondition) .batchSize(500) .noCursorTimeout(false); // 默认 false，靠批次控制而非禁用超时 MongoCursor<Document> cursor = iterable.iterator(); try { while (cursor.hasNext()) { Document fileSet = cursor.next(); String id = fileSet.getString("_id"); // 业务处理逻辑 } } finally { cursor.close(); // 必须关闭，否则连接池会被耗尽 }

关键参数对照如下：

noCursorTimeout(true)看似能一劳永逸解决 -5，但它会让服务端一直保留游标，游标泄漏时内存和句柄会被持续占用，生产环境不建议无脑开。正确做法是估算单批处理耗时，让batchSize对应的数据量在 10 分钟内能处理完，这样客户端会自然地在超时前再次联系服务端，游标就被续上了。

连接串里也建议显式加上超时参数，避免网络层先于游标层断开：

mongodb://user:pass@host:27017/db?socketTimeoutMS=30000&connectTimeoutMS=10000&maxPoolSize=50

socketTimeoutMS控制单次读写等待，maxPoolSize控制连接池上限。池子太小会在高并发下排队，间接拉长单批处理时间，反而更容易触发 -5。

4. 复现 -5 并验证请求成功的完整步骤

要确认问题真的被解决，得先能稳定复现它。下面这套步骤可以帮你把 -5 复现出来，再验证修复是否生效。

第一步，构造一个慢处理场景。把batchSize设成 1000，然后在while循环里对每条文档Thread.sleep(1000)。这样一批 1000 条需要约 1000 秒，远超 10 分钟，游标必然过期。运行后你会看到类似报错：

com.mongodb.MongoCursorNotFoundException: Query failed with error code -5 and error message 'Cursor id 1234567890 not found on server'

第二步，定位日志。在 Java 侧打开驱动日志，加上 JVM 参数：

-Dorg.slf4j.simpleLogger.log.org.mongodb.driver=debug

日志里会打印每次getMore的游标 ID 和耗时。如果看到某个游标 ID 在两次getMore之间间隔超过 600 秒，基本可以确认是处理太慢导致过期。

第三步，修复后重新验证。把batchSize降到 200，去掉sleep，或者把慢处理改成异步。再次运行，观察日志里getMore的间隔是否稳定在几十秒内。如果每批都在超时窗口内完成，-5 就不会再出现。

第四步，验证统一通道侧是否正常。用 curl 发一个最小请求，确认 Base URL 和 Key 没问题：

curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的TaoTokenKey" \ -H "Content-Type: application/json" \ -d '{"model":"你的ModelID","messages":[{"role":"user","content":"ping"}]}'

返回 200 且带choices字段，说明通道正常。如果这里报 401，那是 Key 问题，跟 -5 无关，别混在一起排查。

第五步，做一次端到端回归。让 Java 应用在正常业务负载下跑一轮完整查询，统计getMore次数和总耗时。如果总耗时被拆成多个小于 10 分钟的批次，且没有 -5，就说明配置生效了。

5. 常见报错对照与排查清单

排查时最容易把不同错误混为一谈，下面按真实报错逐条对照。

MongoCursorNotFoundException: error code -5：游标在服务端过期。看batchSize是否过大、单批处理是否超过 10 分钟、是否有跨线程持有游标。修复方向是调小批次、加快处理、及时close()。

401 Unauthorized：这是统一通道侧的 Key 问题，不是 MongoDB 的。检查Authorization: Bearer格式、Key 是否复制完整、是否用了过期 Key。去 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 重新生成一个再试。

local proxy failed：本地网络出口或代理配置异常。检查系统代理、环境变量HTTP_PROXY/HTTPS_PROXY是否指向了不可用地址。这类问题跟游标无关，但会表现为请求整体失败。

reading choices相关报错：通常是响应体解析失败，常见于 Base URL 拼错导致返回了 HTML 错误页。确认 Base URL 是https://taotoken.net/api，不要多加/v1或漏掉/api。

OAuth相关报错：多见于 Claude Code 这类工具的登录态问题。参考接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 重新配置，确保用的是 API Key 而非 OAuth 流程。

如果你用 CC Switch、Cline MCP 或 Codex 的auth.json，务必把三件套写全：Base URL、Key、Model ID。以auth.json为例：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoTokenKey", "model": "你的ModelID" }

少写 Model ID 会报模型不存在，少写 Key 会报 401，Base URL 写错会报 404 或reading choices。这三类都不是 -5，排查时要先分清。

排查清单可以按这个顺序走：先确认报错码是不是 -5；是 -5 就查游标生命周期；不是 -5 就查通道三件套；通道没问题再查网络出口。顺序错了会在无关方向上浪费大量时间。

6. 长期编码与 Agent 场景的接入建议

如果你的 Java 项目里除了 MongoDB 查询，还有大量代码生成、Agent 编排、批量任务，建议把长期编码类任务走 Coding Plan，入口是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。这样模型调用的配额和通道跟数据库访问分开管理，排查 -5 时不会因为模型侧限流而干扰判断。

对于需要频繁验证模型输出的场景，直接用模型对话页 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 做快速验证，比在 Java 代码里反复改配置高效得多。验证通过后再把参数固化到项目配置里。

最后给一个实用习惯：在 Java 项目里把 MongoDB 连接参数和 TaoToken 通道参数分别放在两个配置文件，不要混在一个 properties 里。这样出问题时能一眼看出是数据库侧还是通道侧，-5 和 401 也不会再互相甩锅。游标超时这类问题，本质是时间预算问题，把每批处理耗时压到超时窗口的三分之一以内，基本就不会再遇到 -5。