TypeError: ‘NoneType’ object is not subscriptable

快速结论：该报错在 RAGFlow 启用 TOC Enhance（目录增强）功能进行检索时触发，原因是代码期望每个文本块（chunk）包含 content_ltks 字段，但实际接收到了 None（例如某个文本块在 Elasticsearch 中缺失或未正确解析）。优先排查文档是否在启用 TOC Enhance 的情况下完成解析，以及 Elasticsearch 索引健康状况。

问题场景

用户在 RAGFlow 中上传文档并启用 TOC Enhance 进行解析，随后在检索时也启用 TOC Enhance，系统抛出运行时错误。使用的 RAGFlow 镜像版本为 v0.21.1-121-g4bbbf923（Docker nightly 版本）。

报错原文

2025-12-24 16:44:10,964 ERROR    18 'NoneType' object is not subscriptable
Traceback (most recent call last):
  File "/ragflow/agent/tools/base.py", line 130, in invoke
    res = self._invoke(**kwargs)
  File "/ragflow/common/connection_utils.py", line 59, in wrapper
    raise result
  File "/ragflow/common/connection_utils.py", line 43, in target
    result = func(*args, **kwargs)
  File "/ragflow/agent/tools/retrieval.py", line 189, in _invoke
    cks = settings.retriever.retrieval_by_toc(query, kbinfos["chunks"], [kb.tenant_id for kb in kbs], chat_mdl, self._param.top_n)
  File "", line 106, in retrieval_by_toc
  File "/ragflow/rag/nlp/search.py", line 577, in retrieval_by_toc
    "content_ltks": chunk["content_ltks"],
TypeError: 'NoneType' object is not subscriptable
2025-12-24 16:44:10,966 ERROR    18 Runtime Error: 'NoneType' object is not subscriptable

原因分析

根因在 rag/nlp/search.py 文件的 retrieval_by_toc 方法中（第 577 行附近），代码在没有对 content_ltks 字段做空值检查的情况下直接进行下标访问。当某个文本块在 Elasticsearch 中不存在（返回 404）或该字段为空时，chunk["content_ltks"] 接收到 None，从而触发 TypeError: 'NoneType' object is not subscriptable。可能原因包括：

文档解析时未启用 TOC Enhance，但检索时开启了该功能，导致部分文本块没有 content_ltks 字段。
部分文本块未能成功索引到 Elasticsearch，或索引被破坏。
Elasticsearch 索引健康状态异常。
近期对 TOC 和文本块处理的修改（如 PR #11685、PR #11785）可能引入了兼容性问题。

环境排查

确认 RAGFlow 镜像版本（当前 Issue 使用 v0.21.1-121-g4bbbf923 nightly 版本）。
检查 Elasticsearch 索引健康状态，例如使用 curl http://es01:9200/_cluster/health 查看集群状态。
确认文档解析时的 TOC Enhance 开关是否与检索时的开关一致。
检查索引中文档是否存在对应的 content_ltks 字段。

解决步骤

重新解析文档：确保在解析文档时启用 TOC Enhance，以使每个文本块都包含 content_ltks 字段。
检查 Elasticsearch 索引：确认所有文本块均已成功写入索引，并且数据完整。对于返回 404 的文档 ID，需排查索引录入过程。
更新到最新 nightly 版本：可优先尝试。最近多个 PR（如 #11685、#11785）改进了 TOC 和文本块处理流程，升级可能避免该问题。
代码层面修复（建议）：如果开发者可修改代码，建议在 rag/nlp/search.py 的 retrieval_by_toc 方法中，读取 chunk["content_ltks"] 前增加空值检查，例如：
```
if chunk is None or not chunk.get("content_ltks"):
    # 记录日志并跳过该文本块
    continue
```

验证方法

完成上述步骤后，重新执行以下操作：上传文档 → 解析文档（启用 TOC Enhance）→ 检索（启用 TOC Enhance）。如果不再抛出 TypeError: 'NoneType' object is not subscriptable，且检索结果正常返回，则问题已解决。

参考来源

infiniflow/ragflow #12170

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

TypeError: ‘NoneType’ object is not subscriptable