> ## Documentation Index
> Fetch the complete documentation index at: https://dify-6c0370d8-release-1-16-0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排查

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

> 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/cli/troubleshooting)。

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

完整的退出码对照表和错误对象结构，详见 [输出格式与退出码](/zh/cli/reference/output-formats-and-exit-codes)。

## 版本兼容性

### `version_skew`（difyctl 与服务器版本不匹配）

`difyctl` 随每个 Dify 版本一同发布，并与特定的服务器版本相匹配，因此任何一方的版本变化都可能导致两者不同步。它有两种表现，都会以 `6` 退出：

* **Dify 服务器升级后**，你现有的 `difyctl` 版本过旧。服务器会以 HTTP `426` 拒绝它，并提示升级。
* **你的 `difyctl` 比服务器更新**，此时它会在发送请求前停止，并提示服务器版本低于它所支持的版本。

1. 确认是版本不匹配问题：

   ```bash theme={null}
   difyctl version
   ```

   出现 `Compatibility: incompatible …` 行或升级提示，即可确认。

2. 重新安装与服务器相匹配的 `difyctl`：将 `DIFY_VERSION` 设置为服务器的 Dify 发布标签（如果服务器运行的是最新版本，则可省略），然后重新运行安装脚本。详见 [安装](/zh/cli/install)。

退出码：`6`。

## 认证错误

### `auth_expired`

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

1. 重新认证：

   ```bash theme={null}
   difyctl auth login
   ```

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

退出码：`4`。

### `not_logged_in`

目标主机没有活跃会话。

1. 登录：

   ```bash theme={null}
   difyctl auth login --host <url>
   ```

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

退出码：`4`。

### `access_denied`

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

重新运行并批准请求：

```bash theme={null}
difyctl auth login
```

退出码：`4`。

## 应用错误

### 应用未找到（HTTP 404）

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

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

   ```bash theme={null}
   difyctl get app
   ```

2. 核对 ID 后重新运行。

退出码：`1`。

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

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

退出码：`1`。

## 工作流错误

### 工作流校验错误（HTTP 422）

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

1. 查看应用的输入 schema：

   ```bash theme={null}
   difyctl describe app <id>
   ```

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

退出码：`1`。