# 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](/configuration/manifest-json/#providers-on-your-own-instance) |
| `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](/policies/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.

1. Check your account session: `swy whoami`. If nothing is signed in, run `swy login`.
2. Check the provider connection: `swy auth status`. If the provider isn't listed, run `swy auth connect <provider>`.
3. 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](/cli/authentication/) for the full connect/disconnect/reconnect flow.

### 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](/guides/multi-tenant/).

### 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.

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

See [policies.json](/configuration/policy-json/) for the full schema, [Policy Rules](/policies/policy-rules/) for how conditions are evaluated, and [Human approval](/policies/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`.

1. Confirm what's actually enabled: `swy list tooling`.
2. If the tool exists in an installed integration but isn't enabled yet, add it: `swy add <canonical_id>`.
3. 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:

```text
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`.

```text
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.

1. Check the exact schema the tool expects: `swy info <canonical_id>`.
2. 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.

1. 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`.
2. Check it: `swy doctor` lists every provider whose base URL is still not set.

See [Providers on your own instance](/configuration/manifest-json/#providers-on-your-own-instance).

### Network or connectivity issues

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

```bash
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](/reference/commands/) 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](/policies/human-approval/). |

Version-2 files add `ALLOW`, `MODIFY`, `REDACT`, and `TRUNCATE`. See [Action Types](/configuration/policy-json/#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](https://discord.gg/zuSXSv5GWs) for the fastest response.
- **Email**: [hello@swytchcode.com](mailto:hello@swytchcode.com)