Skip to main content

When difyctl encounters an error, it writes a message to stderr. With -o json active, errors are also single-line JSON with a stable code field and an actionable hint.

For the full exit-code table and error object shape, see Output Formats and Exit Codes.

Version Compatibility#

version_skew (difyctl and the server don’t match)#

difyctl ships with each Dify release and is matched to a server version, so a version change on either side can leave the two out of sync. It surfaces in two ways, both exiting 6:

  • Your Dify server was upgraded and your existing difyctl is now too old. The server rejects it with HTTP 426 and prints an upgrade message.
  • Your difyctl is newer than your server, so it stops before sending the request, reporting that the server is older than it supports.

  1. Confirm it’s a version mismatch:

    A Compatibility: incompatible … line, or an upgrade message, confirms it.

  2. Reinstall difyctl so it matches your server: set DIFY_VERSION to your server’s Dify release tag (or omit it if your server runs the latest release), then re-run the install script. See Install for details.

Exit code: 6.

Authentication Errors#

auth_expired#

Your session has expired and difyctl can no longer make authenticated requests.

  1. Re-authenticate:

  2. Re-run the failed command.

Exit code: 4.

not_logged_in#

No active session exists for the requested host.

  1. Sign in:

  2. Re-run the failed command.

Exit code: 4.

access_denied#

You denied the sign-in request, or canceled it before approving, so nothing was authorized.

Re-run and approve the request:

Exit code: 4.

App Errors#

App not found (HTTP 404)#

The App ID you specified doesn’t exist or isn’t accessible to your token. Surfaces as server_4xx_other with HTTP status 404.

  1. List apps you can access:

  2. Verify the ID and re-run.

Exit code: 1.

Service API disabled (HTTP 403 from server)#

The app exists, but its Service API is turned off in the Dify console. The app owner must enable it. A 403 surfaces as server_4xx_other.

Exit code: 1.

Workflow Errors#

Workflow validation error (HTTP 422)#

A Workflow app rejected your inputs. The error message lists which required inputs are missing or invalid.

  1. Inspect the app’s input schema:

  2. Update your --inputs JSON to match.

Exit code: 1.