Troubleshooting & FAQ

Symptom → cause → fix, keyed to exit codes where one applies. The full 0–12 catalog with retry rules is in Exit Codes.

"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). 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.

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.

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.

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.

Read this page as markdown — the copy your coding agent fetches.