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. This page covers the errors you’re most likely to hit, grouped by the operation that triggered them.
For the full exit-code table and error object shape, see Output Formats and Exit Codes.
Authentication Errors
auth_expired
Your session has expired and difyctl can no longer make authenticated requests.
-
Re-authenticate:
-
Re-run the failed command.
Exit code: 4.
not_logged_in
No active session exists for the requested host.
-
Sign in:
difyctl auth login --host <url>
-
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.
-
List apps you can access:
-
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.
-
Inspect the app’s input schema:
difyctl describe app <id>
-
Update your
--inputs JSON to match.
Exit code: 1. Last modified on June 25, 2026
