> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Results, Errors, and Exit Codes

> Read what a difyctl command prints, check how a run ended, and act on errors, exit codes, retries, and the rate limit

## Where Output Goes

A command's result is always JSON on stdout. Errors and notices go to stderr:

* Errors: as text in your terminal, and as JSON when you send stderr to a file or another program, such as with `2> errors.log`. To get errors as JSON in your terminal too, add `--json`.
* Notices, such as `stream ended early: …`: always as plain text.

## Read a Run's Result

The result of a `run console_app` command holds the app's answer and the IDs you'll need next:

| Field | Holds |
| :- | :- |
| `text.answer` | The response from a Chatbot, legacy Agent, Chatflow, or Text Generator app. Empty for a Workflow. |
| `outputs` | A Workflow's answer, keyed by its Output node's variables. For a Chatflow, the reply again, with any files it returns. |
| `run_id` | For a Workflow or Chatflow, the run's ID, which `describe run` and `get run node` take. |
| `conversation_id` | For a Chatbot, legacy Agent, or Chatflow, the ID to pass back with `--conversation-id` to continue the conversation. |

### Check How a Run Ended

In a script, read the result's `status`. A run that finished, paused, or was cut off exits 0 all the same, and `status` tells them apart:

* `ended`: the run finished.
* `suspended`: the run paused at a Human Input form.

  When `difyctl` can answer it, `hints` holds one command per action button; when the form went only to other recipients, `hints` is `[]`. To answer the form or follow the run, see [Answer a Human Input Form](https://docs.dify.ai/en/cli/run-apps.md#answer-a-human-input-form).
* `incomplete`: the result was cut off before the run ended, for example when you press Ctrl+C. It holds only what arrived by then.

  A Workflow or Chatflow run keeps going on the server: pass the result's `run_id` to `difyctl describe run` to see how it ends, or to [`stop run`](https://docs.dify.ai/en/cli/run-apps#stop-a-run) to stop it. If there's no `run_id`, find the run in the app's [list of running runs](https://docs.dify.ai/en/cli/run-apps.md#stop-a-run).
* `failed` (exit code 1): the run failed or was stopped, and `error.message` says why.

  For a Workflow or Chatflow, pass the result's `run_id` to `difyctl describe run` to tell the two apart: a stopped run's `status` becomes `stopped`.

A failed run prints its result on stdout like any other run, and nothing goes to stderr. For example, a Workflow run without its required input:

```json theme={null}
{
  "status": "failed",
  "text": {
    "answer": ""
  },
  "hints": [],
  "run_id": "f16c3509-ef54-4618-ae93-770724ab278d",
  "total_tokens": 0,
  "error": {
    "message": "topic is required in input form"
  }
}
```

## Read an Error

A command that fails before it produces a result prints nothing on stdout and an error on stderr. Here's the error as JSON for an app ID that doesn't exist:

```json theme={null}
{
  "error": {
    "code": "server_error",
    "message": "app not found",
    "http_status": 404,
    "method": "GET",
    "url": "https://dify.example.com/openapi/v1/apps/00000000-0000-4000-8000-000000000000",
    "server": {
      "code": "not_found",
      "message": "app not found",
      "status": 404
    }
  }
}
```

Every error has a `code` and a `message`. Branch on `code`. Depending on the failure, the error also carries:

* `hint`: what to try next, as a sentence, such as `run difyctl help get console_app`.
* `http_status`, `method`, `url`, and `server` (the server's own error), when the server returned the error. For `server_error`, branch on `http_status` or `server.code`, such as `404` and `not_found` above.
* `details`, when a value fails `difyctl`'s own check (`input_invalid`): each field that failed, with its flag and the reason, such as `"field": "--limit", "msg": "must be integer"`.

In a terminal, the error's first line shows the server's own code when there is one. For the missing app above, that's `not_found: app not found`. Take the codes your script branches on from the JSON, where this one is `server_error`.

When `message` doesn't explain the failure, add `--verbose` to include `raw_response`, the server's full response.

## Exit Codes

Every command exits with one of these codes:

| Exit code | Means | Error codes |
| :- | :- | :- |
| 0 | Success, including a run that paused (`suspended`) or was cut off (`incomplete`) | |
| 1 | A [failed run](#check-how-a-run-ended), or an error the other rows don't cover, such as a server or network error | `server_error`, `network_connection`, `keyring_unavailable`, `skill_missing`, `unknown` |
| 2 | `difyctl` rejected the command before sending it: an unknown flag, a missing required flag, or a value of the wrong type | `usage_invalid_flag`, `usage_missing_arg`, `input_invalid`, `config_invalid_key`, `config_invalid_value` |
| 4 | You're not signed in, your sign-in expired, or you don't have access | `not_logged_in`, `auth_expired`, `access_denied` |
| 6 | The command isn't on your server, or `difyctl` couldn't get your server's command list | `unknown_op`, `catalog_unavailable` |
| 7 | You hit the [rate limit](#rate-limit) | `rate_limited` |

On exit code 1, look at stdout first: a failed run's result is there. Any other error is on stderr.

To fix a specific error, see [Troubleshooting](#troubleshooting).

## Retry a Failed Command

Commands that read, such as `get` and `describe`, are safe to retry. `help` shows each command's label, `read`, `write`, or `destructive`, next to its description.

Before you retry a `write` or `destructive` command, check whether the first attempt took effect, for example with the matching `get` or `describe` command. A run is `write`, and retrying it starts a new run.

After exit code 7, any command is safe to retry, runs included: a command refused by the [rate limit](#rate-limit) did nothing on the server.

Exit codes 2 and 4 come back on every retry until you fix the cause, such as a wrong flag or an [expired sign-in](https://docs.dify.ai/en/cli/manage-sign-in.md#renew-your-sign-in).

### Rate Limit

When a command exits 7, wait a minute, then retry.

Each sign-in and each [personal access token](https://docs.dify.ai/en/cli/personal-access-tokens.md) has its own limit of 60 requests a minute. On a self-hosted server, set [`OPENAPI_RATE_LIMIT_PER_TOKEN`](https://docs.dify.ai/en/self-host/deploy/configuration/environments#dify-cli-and-programmatic-api) to change the limit, or set it to `0` to turn it off.

## Troubleshooting

| Message | Code | What to do |
| :- | :- | :- |
| `invalid bearer` | `auth_expired` | Your sign-in expired or was ended. [Sign in again](https://docs.dify.ai/en/cli/manage-sign-in.md#renew-your-sign-in). For a personal access token, find the fix in [its Troubleshooting](https://docs.dify.ai/en/cli/personal-access-tokens.md#troubleshooting). |
| `not logged in: …` | `not_logged_in` | Sign in. If you already did, point `DIFY_CONFIG_DIR` at the folder you signed in with. |
| Varies, such as `insufficient workspace role` | `access_denied` | Your workspace role, or a workspace setting such as who can install integrations, doesn't allow this. |
| `workspace not found` | `server_error` | The account isn't in the workspace the command works in: the one in `DIFY_WORKSPACE_ID` or `--workspace-id`, or the one the app belongs to. Check the ID against `difyctl get workspace`. If it's the right workspace, have the account added to it. |
| `no command or server operation named <words>` | `unknown_op` | Check the command with `difyctl help`. If it's spelled right, your server's Dify version doesn't have it. |
| `failed to fetch the catalog: …` | `catalog_unavailable` | Check that your server is up and that you signed in to the right address. |
| `<method> <url> timed out after <ms>ms` | `network_connection` | Raise [`http.timeout`](https://docs.dify.ai/en/cli/reference/configuration#settings). |
| `Internal Server Error`, HTTP 503, on every command that uses your sign-in | `server_error` | On a self-hosted server, make sure `ENABLE_OAUTH_BEARER` is set to `true`. |
| `skills_disabled: …`, HTTP 503, on every skill command | `server_error` | On your server, make sure [`ENABLE_SKILL`](https://docs.dify.ai/en/self-host/deploy/configuration/environments#console-features) is set to `true`. |
| `skill_not_found: …` | `server_error` | Check the skill ID with `get skill`. |
| `skill_version_not_found: …` | `server_error` | Check the version ID with `get skill version`. |
| `skill_name_conflict: …` on `import skill` | `server_error` | Another skill already has this name. If that's the skill you meant to update, pass its ID from `get skill` with `--skill-id`. Otherwise, rename yours in its `SKILL.md`. |
| `skill_name_mismatch: …` on `import skill` | `server_error` | The `name` in your `SKILL.md` doesn't match the name of the skill you passed with `--skill-id`. Change it back, or leave out `--skill-id` to import the folder as a new skill. |
| `draft_changed: …` on `import skill` | `server_error` | The skill changed after you read its `draft_hash`, such as an edit to its draft, a publish, or a rename. Run `describe skill` and save the new hash, then export the current draft and merge its changes into your folder. Import with the saved hash. Importing your folder as it is would wipe those changes. |
| `skill_package_invalid: …` on `import skill` | `server_error` | The folder isn't a valid skill package. For the format, see [Agent Skills](https://agentskills.io/home). |
| `skill_package_invalid: …` on `publish skill` or `export skill` | `server_error` | The draft's `SKILL.md` frontmatter is invalid. In Dify, fix the field or line the error names. |
| `request_entity_too_large: …` on `import skill` | `server_error` | The folder has too many files or is too large for your server's [skill package limits](https://docs.dify.ai/en/self-host/deploy/configuration/environments.md#upload_skill_file_size_limit). Remove files the skill doesn't need, or have your server admin raise the limit the message names. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.