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.

​
Authentication Errors

​
auth_expired

Your session has expired and difyctl can no longer make authenticated requests.
  1. Re-authenticate: 
    difyctl auth login
  2. Re-run the failed command.
Exit code: 4.

​
not_logged_in

No active session exists for the requested host.
  1. Sign in: 
    difyctl auth login --host <url>
  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: 
difyctl auth login
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: 
    difyctl get app
  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.

​
App access not permitted (HTTP 403, user_not_allowed_for_private_app)

The app exists and its Service API is on, but its access is restricted and your identity isn’t on its allow-list. Apps imported from DSL with import studio-app are private by default, so a freshly imported app returns this until its access is opened. In the Dify console, set the app’s web-app access to public, or have an administrator add you to its allowed members. Then re-run. 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: 
    difyctl describe app <id>
  2. Update your --inputs JSON to match.
Exit code: 1.

​
Connection Errors

​
Can’t reach the host

Commands fail before authentication, or the server probe in difyctl version can’t read a version. Either the host is wrong, or the deployment isn’t set up to accept difyctl connections.
  1. Confirm --host is your deployment’s console API URL (CONSOLE_API_URL), not the web URL.
  2. If the host is correct and difyctl still can’t connect, ask your administrator to enable difyctl access on the deployment.
Exit code: 1.