Troubleshooting

Fix common difyctl errors with their explanations, exit codes, and solutions

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.

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.