SDKTroubleshooting

Troubleshooting

Exit codes

SituationResult
Run completedExit code 0.
Unknown command or bad usageExit code 2. Nothing is sent.
The run failed: API error, budget limit, turn limit or an error during the runExit code 1. With json output, is_error is true.

A run that is stopped by --max-turns or --max-budget-usd exits with 1, and its result subtype says which limit stopped it.

”Not signed in”

The CLI needs a signed-in account or an API key. Run syntic login, or set SYNTIC_API_KEY before the run. Check the state with syntic auth status.

A run stops without an answer

  • Check --max-turns and --max-budget-usd. A run that reaches either limit stops.
  • Check the permission mode and the allow rules. In a -p run, a tool call that needs approval is refused, and the agent is told why. Allow the tools the task needs with --allowed-tools.

A tool call is refused

Permission rules are checked before the tool runs. Deny rules win over every mode except checks that always ask. Look at /permissions in an interactive session, or the permissions section in Permission rules, to see which rule applied.

Provider errors

  • If --fallback-model is set, the run can move to that model when the primary model is overloaded. Confirm the behaviour for your account before you rely on it.
  • Authentication and invalid-request errors do not fall back. Fix the account or the request.

Session cannot be resumed

Resume by session id, a unique id prefix or an exact title with --resume <id>, or the latest session with --continue. If two sessions share a title, both are listed and nothing is resumed; use the id. See Sessions.

For install problems, see Install and sign-in troubleshooting.