Troubleshooting

This page covers what to do when a swy command or tool execution fails - exit codes, common failure modes, and the diagnostic commands to run first.

Exit codes

Every swy exec (and related) call returns a standard exit code, making it easy to handle failures in scripts and CI/CD pipelines.

Exit Code	Meaning
`0`	Execution completed successfully
`1`	Execution failed
`2`	Invalid input or validation error
`3`	Authentication failed
`4`	Execution blocked by policy
`5`	Tool not found

Common failure modes

Authentication failed (exit code 3)

The account session or provider credentials Swytchcode needs weren’t available or had expired.

Check your account session: swy whoami. If nothing is signed in, run swy login.
Check the provider connection: swy auth status. If the provider isn’t listed, run swy auth connect <provider>.
If you’re using SWYTCHCODE_TOKEN in CI, confirm it’s actually set in the job environment - the CLI reads it only from the process environment, never from a .env file.

See Authentication for the full connect/disconnect/reconnect flow.

Execution blocked by policy (exit code 4)

A rule in .swytchcode/integrations/policies.json matched the request and blocked it before any API call was made.

List your active policies: swy policy list.
Look up the specific violation: swy audit policy (add -n 5 to see the most recent few).
Adjust or remove the offending rule with swy policy add/swy policy remove <id>, then re-validate: swy policy validate.

See policies.json for the full schema, Policy Rules for how conditions are evaluated, and Human approval if the command was held for a person instead of blocked.

Tool not found (exit code 5)

The canonical ID you executed hasn’t been enabled in this project’s tooling.json.

Confirm what’s actually enabled: swy list tooling.
If the tool exists in an installed integration but isn’t enabled yet, add it: swy add <canonical_id>.
If the integration itself isn’t installed, fetch it first: swy get <project>.

swy sync [project] re-fetches the integration bundles from the backend for integrations already installed via swy get - it doesn’t install anything new and doesn’t touch tooling.json. Two errors are common:

no integrations found: run swy get <project>

No project’s integrations have been fetched yet. Run swy get <project> first (or swy bootstrap to fetch everything already declared in tooling.json.integrations), then retry swy sync.

fetch provider bundles: ...

swy sync reached the network/auth layer but the request itself failed - usually a connectivity problem or an expired session. Check swy whoami and swy doctor --network.

Invalid input or validation error (exit code 2)

The request didn’t match the tool’s input schema before it was sent.

Check the exact schema the tool expects: swy info <canonical_id>.
Re-run with --dry-run to validate inputs without executing: swy exec <canonical_id> --dry-run.

Network or connectivity issues

If a command hangs, times out, or can’t reach the registry:

swy doctor --network

This checks every network endpoint the CLI may contact and reports its current status, alongside your local tooling.json, integration bundles, and auth environment.

Diagnostics reference

Command	What it tells you
`swy doctor`	Local diagnostics: tooling, bundles, auth, permissions, secrets.
`swy doctor --network`	Same, plus reachability of every network endpoint the CLI may contact.
`swy audit network -n 10`	Recent outbound network calls: host, method, status, duration.
`swy audit policy -n 10`	Recent policy-violation log entries.
`swy audit stats`	Local execution history: total runs, success rate, last run.
`swy whoami`	Current authentication state.

See the full CLI Reference for every flag and subcommand.

Policy action types

When writing a policies.json rule, these action types are currently supported for allow / deny:

Action	Description
`AUTH_FAILED`	Authentication failed.
`POLICY_BLOCKED`	Request blocked by policy.

To hold a command until a person confirms it, see Human approval.

Still stuck?

If none of the above resolves it, reach out - include the command you ran, the exit code, and (if relevant) the output of swy doctor.

Discord: Join the Swytchcode community for the fastest response.
Email: [email protected]