Troubleshooting

Troubleshooting / 故障排查

← Wiki home / 手册首页 · English · 中文 · Latest Release / 最新版

Safe rule / 安全原则： keep the error message and activity log first. Do not delete the data root, Runtime, models, or indexes until the symptom and scope are understood.
先保留界面错误和活动日志；在明确现象与影响范围以前，不要删除数据目录、Runtime、模型或索引。

English

Symptom	What it usually means	First safe action
Runtime is still detecting	Startup validation has not finished	Wait for the final state; query is intentionally disabled
Runtime appears installed but needs repair	Files exist but validation or a required component failed	Refresh detection once, then use Runtime repair and inspect its log
Query uses CPU in Auto	CUDA is unavailable for the current stage or the workload does not fit current resources	Read the Query Console resource reason; do not reinstall blindly
Semantic recall works but reranker is skipped	The optional second model could not be loaded safely	Results remain usable; release resources or keep the safe result
Lexical recovery message	The isolated semantic worker failed or exited	Retry after checking Runtime/resources; the UI and returned lexical result remain safe
Query returns no semantic candidates	Vector index/model may be missing, disabled, incompatible, or the threshold is too strict	Check query mode and index state before rebuilding
Live watch updates too often	Quiet time is too short or a sync/editor tool creates many events	Increase the quiet period and exclude generated history where possible
Live watch still updates after stop request	A worker may be finishing a safe cancellation point	Wait for the final stopped state; report logs if updates continue afterward
Tika installation fails	Network, JRE, JAR, path, or security software issue	Use the UI's manual-install location and Tika manual install
MCP returns index-not-ready	Desktop index has not been built for the active data root	Build with the desktop app and confirm both processes use the same data root
MCP client rejects stdio	The client, configuration page, or installed version may use a different transport schema	Check current client docs before adding a proxy; for OpenClaw see the current guide

Before reinstalling

Do not immediately delete the data root, Runtime, models, or indexes. First:

1. copy the user-facing error and relevant activity-log block
2. note which knowledge bases were selected
3. record the device setting
4. refresh Runtime detection once
5. check free disk, Windows Commit, RAM, and GPU memory
6. retry with one small knowledge base when scope may be involved

What to include in a bug report

• application version and package type
• Windows version
• CPU/GPU model and driver status when relevant
• exact steps from launch to failure
• Query Console message
• complete related activity-log block
• whether the issue reproduces after restart

Remove private paths, note titles, query text, workspace names, and retrieved content before publishing logs.

中文

现象	通常代表什么	第一个安全处理方法
Runtime 仍在检测	启动验证尚未完成	等待最终状态；此时禁用查询是有意设计
Runtime 已安装但提示待修复	文件存在，但验证或必要组件失败	刷新检测一次，再使用 Runtime 修复并查看日志
Auto 查询使用 CPU	当前阶段无法使用 CUDA，或者任务不适合当前资源	阅读查询台的资源原因，不要盲目重装
语义召回成功但跳过重排	可选的第二个模型无法安全加载	结果仍可使用；释放资源后重试，或者接受安全结果
提示字面恢复	隔离语义子进程失败或退出	检查 Runtime/资源后重试；主界面和已返回结果仍然安全
没有语义候选	向量索引或模型可能缺失、关闭、不兼容，或阈值过严	先检查查询模式和索引状态，再决定是否重建
热监听更新太频繁	安静时间过短，或同步/编辑器产生大量事件	增加安静时间，并尽量排除自动历史目录
请求停止后仍出现更新	工作进程可能正在到达安全取消点	等待最终停止；最终停止后仍更新再提交日志
Tika 安装失败	网络、JRE、JAR、路径或安全软件问题	使用界面显示的手动安装位置，并看 Tika 手动安装
MCP 返回索引未就绪	当前数据目录下尚未通过桌面版建库	用桌面版建库，并确认两个进程的数据目录一致
MCP 客户端拒绝 stdio	客户端、配置界面或已安装版本可能使用不同传输结构	引入代理前先核对当前客户端文档；OpenClaw 见当前说明

重装之前

不要一遇到问题就删除数据目录、Runtime、模型或索引。先：

1. 保存界面错误和相关活动日志块
2. 记录选中了哪些知识库
3. 记录设备设置
4. 刷新一次 Runtime 检测
5. 检查磁盘、Windows Commit、内存和显存
6. 如果可能与范围有关，用一个小知识库重试

反馈 Bug 时应包含

• 软件版本和使用的发布包类型
• Windows 版本
• 相关时的 CPU/GPU 型号与驱动状态
• 从启动到故障的准确步骤
• 查询台提示
• 完整相关活动日志块
• 重启后是否仍能复现

公开日志前，请删除私人路径、笔记标题、查询文字、工作区名称和检索内容。

---

Previous / 上一篇： ← MCP Integration / MCP 接入 · Developer reference / 开发者参考： Development and Architecture / 开发与架构 →