# Troubleshooting & FAQ

Symptom → cause → fix, keyed to exit codes where one applies. The full 0–12 catalog with retry rules is in [Exit Codes](https://omnicli.io/docs/exit-codes.md).

## "My agent can't log in"

**That's by design, not a bug.** Every login is human-only: an agent that tries `omni-cli account login` or `omni-cli <platform> login` gets exit 6 (`interactive_required`). Account sign-in is a browser device flow, and platform login reads the token only from an interactive terminal — never from a pipe, flag, or environment variable.

**Fix:** a human runs the logins, once per machine — sign the device in, then connect each platform (see [Quickstart](https://omnicli.io/docs/quickstart.md)). After that the agent runs actions on its own; it never needs to authenticate.

## Exit 3 — `context_unresolved`

The CLI couldn't decide between `work` and `personal`. It resolves in order: `--context` flag → `OMNI_CONTEXT` → directory binding → global default → single-logged-in-context inference. With two contexts logged in and none of the above set, resolution fails.

**Fix:** pass `--context work` (or `personal`) on the command, or pin a default with `omni-cli context use work`, or bind the project directory — see [Contexts](https://omnicli.io/docs/contexts.md).

## Exit 4 after switching machines

Exit 4 (`not_authenticated`) means no credential exists for that platform:context *on this machine*. Credentials are per-device: platform tokens live in a local file and the account session is bound to a device key that never leaves the machine. Nothing roams.

**Fix:** treat the new machine as a fresh install — run the install one-liner (or `omni-cli account login`), then log in to each platform again.

## Exit 10 — `entitlement_required`

Two distinct causes:

- **The definition needs to refresh.** The CLI couldn't reach the backend to refresh its signed bundle. Get the machine online and run `omni-cli definitions update`; `omni-cli definitions status` shows the current state.
- **The action is outside the plan.** The subscription lapsed or the action isn't included in the current plan — review it at https://omnicli.io/pricing.

## Exit 11 — `update_required`

The installed binary is below the minimum version the backend accepts. **Fix:** a human runs `omni-cli self-update`. Depending on the plan's policy the CLI may perform this update by itself, in which case exit 11 never surfaces.

## Platform login fails with a valid token

Login validates the credential against the platform before storing it, so a failure here is a real mismatch. The two usual causes:

- **Wrong host** on a host-required platform (Octopus, Jira): the host must be the exact API base URL. A host that answers something for every path can make a typo look like a bad token.
- **Missing email** on an email+token platform (Jira, Bitbucket, PagerDuty): these authenticate with the pair, so the token alone is rejected even when it's valid. Enter both parts at the prompts.

Per-platform token and host details are in [Platform Logins](https://omnicli.io/docs/platform-logins.md).

## Definition changes not showing up

Edits bump the definition's version, but an installed CLI only sees it on its next bundle refresh. **Fix:** force one with `omni-cli definitions update`; `omni-cli definitions status` confirms the active version. See [Definitions](https://omnicli.io/docs/definitions.md).

> Agents should branch on the exit code, never on output text — the complete catalog, including which failures are safe to re-issue, is in [Exit Codes](https://omnicli.io/docs/exit-codes.md).