快速结论:该报错通常出现在自托管 n8n 的 Settings > AI Assistant > “Connect a model” 中,使用自定义 OpenAI-compatible Base URL(如 OmniRoute、LiteLLM、vLLM 等网关/代理)时连接验证失败。请优先查看服务端日志中的验证失败分类(unauthorized / forbidden / quota_exceeded / rate_limited / timeout / unreachable / invalid_response / provider_error)以及经过脱敏的 provider 错误,据此判断是请求未到达网关,还是网关返回的响应结构被拒绝。
适用环境:Issue 中已确认:n8n 1.x / 2.x,Docker / Docker Compose 自托管(Linux),数据库 PostgreSQL 或 SQLite,Node.js 20.x+。涉及的自定义网关包括 OmniRoute、vLLM(含经 LiteLLM 的情况),模型包括 gemini-2.0-flash、gpt-4o-mini、GLM、Gemma。
最快修复方案:暂无确认的一步修复方案。Issue 中提到的修复只有 Gateway 侧的兼容处理(见 kaovilai/copilot-api PR #9 及相关仓库说明),并非 n8n 内置的已验证修复。
注意事项:连接对话框只显示笼统的 “The service returned an unexpected response”,详细原因仅记录在服务端日志中,需要具备日志访问权限。Issue 中另有参与者在后续评论中更正:PR #37156 实际只修改了 `.github/actions/setup-nodejs/action.yml`,与模型连接路径无关,因此不能作为该问题已修复的证据。
问题场景
在自托管 n8n 中进入 Settings > AI Assistant > “Connect a model”,Provider 选择 OpenAI (custom / compatible),填入自定义 Base URL(例如 http://<internal-proxy-host>:20128/v1 或 HTTPS 反向代理地址)、API Key 和模型名(如 gemini-2.0-flash、gpt-4o-mini),点击 Connect 后连接测试失败。该端点通过 curl 能正常完成标准 chat completions 和 tool-calling 校验。另有用户在使用自托管 OmniRoute 实例时遇到相同现象,尝试模型别名后结果不变。
报错原文
The service returned an unexpected response. Check that the URL points to the supported API and try again.
部分网关侧还会出现以下日志:
Unsupported input item type: item_reference (gemma)
KeyError: 'role' (GLM - unhandled error path in vLLM PR #53380 stateless responses handler)
原因分析
根据 Issue 讨论,同一个笼统错误可能由两类彼此独立的问题引起(可能原因):
- n8n 将 UI 上选择的 custom OpenAI-compatible provider 折叠为标准的
openai后端 provider,改为依赖 base-URL 启发式判断,而不是保留显式的 provider 类型。 - 部分本应兼容的网关无法通过严格的
@ai-sdk/openaischema 校验,例如响应中省略了choices[].index,此时 n8n 只报告 “Invalid JSON response” 之类的信息。 - 另有一类路径:连接保存在某些情况下会发送
POST /v1/responses,请求体包含{"type":"item_reference","id":"..."}输入;使用 vLLM Responses API handler(vLLM 本身或经 LiteLLM 接入 GLM、Gemma 等模型)的后端无法解析这类引用,返回 400 或 500,n8n 最终表现为 “unexpected response”。
Issue 中给出的定位线索:自定义端点校验在 packages/cli/src/modules/instance-ai/instance-ai-verification.service.ts 中执行(以提交 4169b55bf3b3 阅读)。它发送一次最小探测请求(generateText,内容 “Reply with OK.”,最大输出 16 tokens,30 秒超时中断),并把失败归入 unauthorized / forbidden / quota_exceeded / rate_limited / timeout / unreachable / invalid_response / provider_error 分类。该分类可以区分“请求从未到达网关”和“请求已到达但响应结构被拒绝”,分类结果与脱敏后的 provider 错误都会写入服务端日志(logVerificationFailure)。
环境排查
- 确认 n8n 版本与部署方式:n8n 1.x / 2.x,Docker / Docker Compose 自托管,Node.js 20.x+。
- 确认数据库类型:PostgreSQL 或 SQLite(Issue 中两类均有出现,未指向特定数据库问题)。
- 确认所用网关类型及版本:OmniRoute、vLLM、LiteLLM 等,并确认其 Responses API 是否支持
item_reference输入项。 - 确认 Base URL 是否可被 n8n 容器访问(内网主机名、端口 20128 或反向代理地址、TLS 证书是否有效)。
- 确认所选模型的响应结构是否符合 OpenAI schema,重点检查
choices[].index等字段是否缺失。
解决步骤
- 先打开 n8n 服务端日志,在点击 Connect 失败后查找
logVerificationFailure相关记录,记录失败分类(unauthorized / forbidden / quota_exceeded / rate_limited / timeout / unreachable / invalid_response / provider_error)和脱敏后的 provider 错误。 - 若分类为 timeout / unreachable,检查 Base URL 在 n8n 容器内是否可达(内网 DNS、端口、反向代理、证书),必要时在容器内用
curl复测同一路径。 - 若分类为 unauthorized / forbidden / quota_exceeded / rate_limited,按网关侧要求检查 API Key 权限、配额与限流设置。
- 若分类为 invalid_response / provider_error,对照网关实际返回的 JSON 检查是否符合 OpenAI schema(如
choices[].index),并在网关侧修复响应格式。 - 若网关是 vLLM / LiteLLM 系且日志出现
item_reference或KeyError: 'role',属于网关对 Responses API 输入项兼容性问题,需在网关侧处理(可参考 kaovilai/copilot-api PR #9 及相关仓库中作者的兼容性修复说明),而不是在 n8n 中修改连接参数。 - 可优先尝试:在网关侧启用/配置严格的 OpenAI 兼容响应(补齐 schema 必需字段、支持或拒绝 Responses API 的
item_reference),再重新 Connect。此步骤为 Issue 中用户反馈的修复路径,n8n 侧的一步修复尚未得到验证。
验证方法
在网关侧修复后,回到 Settings > AI Assistant > “Connect a model” 重新点击 Connect;同时观察服务端日志中新的验证记录,确认不再出现同类失败分类、provider 错误为空或不再是 invalid_response / provider_error,连接对话框显示成功。最终以 Issue 是否被正式关闭和发布说明为准,Issue 讨论中也强调应避免基于不相关的 PR 提前关闭。
参考来源
n8n-io/n8n #36873
kaovilai/copilot-api PR #9
AI 工具推荐
想把多个 AI 模型放在一个入口?
GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型,适合写作、绘图、视频和日常 AI 工作流。
推广链接:通过此链接购买,我可能获得佣金,不影响你的价格。
这个方案解决了吗?
可以继续搜索完整报错,或查看同一工具的其他排查指南。


