07 · TROUBLESHOOTING
从第一条可靠证据开始排查
先区分路径、端口、引擎、模型、网络和客户端层，再处理具体参数。日志中的第一条失败通常比后续连锁错误更有价值。
通用排查顺序
状态→日志→路径 / 端口→引擎能力→最小请求
常见问题
实例启动后立即停止
- 打开服务器日志，找到第一条 error / failed
- 确认模型和可执行文件路径存在
- 检查端口是否已被其他进程占用
- 核对引擎后端与当前硬件、驱动是否匹配
请求返回 401 / 403
- 区分路由 API Key 与内部实例 API Key
- OpenAI 客户端使用 Bearer；Anthropic 可使用 x-api-key
- 确认 Base URL 指向路由端口，而不是某个实例端口
Claude Code 工具调用失败
- 确认目标 llama-server 版本原生支持 Messages
- 在实例中启用 Jinja
- 先使用普通 Messages 请求验证模型与路由
- 不要依赖 Anthropic 云端专属能力
下载无法恢复或校验失败
- 确认源站支持 Range 请求且文件没有更新
- 检查目标磁盘空间和写权限
- 删除明确损坏的部分文件后重新下载
- 不要混合不同版本的 GGUF 分片
仍然无法解决
请附上应用版本、操作系统、llama-server 版本、最短复现步骤和脱敏后的第一条错误日志，在 GitHub Issues 提交问题。
打开 GitHub Issues返回文档首页 →