故障排查

修复常见的 difyctl 错误，附带原因说明、退出码和解决方案

本文档由 AI 自动翻译。如有任何不准确之处，请参考 英文原版。

difyctl 遇到错误时，会将错误信息写入 stderr。启用 -o json 后，错误也会以单行 JSON 输出，其中包含稳定的 code 字段和可操作的 hint。

完整的退出码对照表和错误对象结构，详见 输出格式与退出码。

认证错误

auth_expired

会话已过期，difyctl 无法再发起经过认证的请求。

1. 重新认证：

   difyctl auth login
   

2. 重新运行失败的命令。

退出码：4。

not_logged_in

目标主机没有活跃会话。

1. 登录：

   difyctl auth login --host <url>
   

2. 重新运行失败的命令。

退出码：4。

access_denied

你拒绝了登录请求，或在批准前取消了请求，因此未授权任何操作。

重新运行并批准请求：

difyctl auth login

退出码：4。

应用错误

应用未找到（HTTP 404）

指定的应用 ID 不存在，或当前 token 无权访问。表现为 server_4xx_other，HTTP 状态码为 404。

1. 列出有权访问的应用：

   difyctl get app
   

2. 核对 ID 后重新运行。

退出码：1。

服务 API 已禁用（服务器返回 HTTP 403）

应用存在，但其服务 API 已在 Dify 控制台中关闭。需由应用所有者开启。403 表现为 server_4xx_other。

退出码：1。

工作流错误

工作流校验错误（HTTP 422）

工作流应用拒绝了你的输入。错误信息会列出缺失或无效的必填输入。

1. 查看应用的输入 schema：

   difyctl describe app <id>
   

2. 更新 --inputs JSON 使其匹配。

退出码：1。