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`	Invalid input or validation error, or the provider’s base URL is not set
`2`	Tool not found
`3`	Authentication failed
`4`	The request couldn’t be completed (network error or timeout), or the response couldn’t be read
`5`	Internal error
`6`	Blocked by a policy (or its response was withheld by one)
`7`	Waiting for human approval
`130`	Interrupted (Ctrl+C)

A provider that answers with an error status (4xx or 5xx) still exits 0: the JSON output carries status_code, error_category, and retryable.

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.

A crypto exchange rejects a signed request (401)

An exchange answers 401 for several reasons besides a wrong key:

Clock drift. Run swy doctor. Exchanges reject timestamps more than a few seconds off, so sync the system clock.
Wrong key pair. Check that the API key and the secret belong together and are enabled, then run swy auth connect <provider> again. It checks the pair with the exchange before saving it.
IP allowlist. Many exchanges restrict a key to listed IP addresses. Add this machine’s address on the exchange.
Kraken EAPI:Invalid nonce. The key was used elsewhere with a larger nonce. Create a new key for Swytchcode.

swy exec <tool> --dry-run shows the signed request (with the signature and keys redacted), so you can check the path and query that were signed.

End user not connected, plan limit or setup required (exit code 3)

These come from calls made for an end user of your app (--tenant / tenantId). Check the error’s category:

tenant_not_connected: this end user has not connected the provider. Show them your Connect button; retrying will not help.
setup_required: run swy auth connect <provider> once to choose Default Swytchcode or your own app (or register your own app for a provider that requires one).
plan_limit: your plan’s end-user limit is reached, or the provider needs your own app. The error’s docs_url links to the upgrade page.

If the error says this Swytchcode backend does not support end users, SWYTCHCODE_API_URL points at a backend (for example a self-hosted Enterprise one) that predates end users. The CLI stops rather than use your own account for the end user; upgrade that backend.

See Multi-tenant apps.

Execution blocked by policy (exit code 6)

A rule in .swytchcode/integrations/policies.json matched the request and blocked it before any API call was made. The error JSON has "source": "policy" and names the policy. If it says the call was made but its response is withheld, a response policy hid the result: don’t repeat the call.

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 2)

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` fails

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 1)

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.

Base URL not set (exit code 1)

The error has "category": "base_url_not_set". The provider runs on your own instance (Jira, Salesforce, Oracle and similar), and its endpoint for this mode is still empty, a placeholder like https://<your-domain>.atlassian.net, or the bare http://localhost default. Nothing was sent.

Set your URL as production_endpoint or sandbox_endpoint for the provider in .swytchcode/integrations/manifest.json, or set the environment variable named in the error’s suggested_action, such as SWYTCHCODE_BASE_URL_JIRA_JIRA_PRODUCTION.
Check it: swy doctor lists every provider whose base URL is still not set.

See Providers on your own instance.

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 decisions (blocked, held, changed, hidden).
`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

Action	Description
`POLICY_BLOCKED`	Request blocked by policy.
`AUTH_FAILED`	Request blocked as not authorized.
`RATE_LIMITED`, `QUOTA_EXCEEDED`	Request blocked as over a limit. With a time window, the error includes `retry_after`.
`REQUIRES_APPROVAL`	Request held until a person approves it. See Human approval.

Version-2 files add ALLOW, MODIFY, REDACT, and TRUNCATE. See Action Types.

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]