> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/cli/using-the-cli/troubleshooting.md). # Troubleshooting Common CLI failure modes, in rough order of how often they come up. ## `celigo: command not found` The npm global `bin` directory isn't on your `PATH`. ```bash npm bin -g # prints the directory ``` Add it to your shell rc file: ```bash # bash / zsh echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.zshrc # Windows PowerShell (one-shot) $env:Path = "$(npm bin -g);$env:Path" ``` Or re-install with a Node Version Manager (nvm, volta) that manages `PATH` for you. ## `401 Unauthorized` * Token is missing, expired, or revoked. * You're pointing at the wrong region. A token authenticates only against its own region's base URL. Inspect the active config: ```bash celigo config show celigo profile list ``` Rotate the token with `celigo config set api_token ` and retry. See [Authenticate](/cli/getting-started/authenticate.md). ## `Profile 'x' does not exist` ``` Profile 'x' does not exist. Available: prod, eu (run 'celigo profile list'). ``` The profile NAME is wrong, not the token. Since celigo-cli 2026.9.1 a `--profile` flag or a `CELIGO_PROFILE` value that names no profile fails before any request — even when `CELIGO_API_TOKEN` or `--token` would supply a token — instead of resolving to an empty profile and failing later. * Pick a name from `celigo profile list`. * Check the session: `echo $CELIGO_PROFILE`. A stale value bound in a shell rc file or an agent harness selects the wrong profile for every command. * Do **not** write a token in response. `celigo config set api_token --profile x` creates the misspelled profile (or overwrites another profile's token) — that is the failure chain this check exists to stop. The `profile`, `config`, and `skills` commands and the offline tree verbs (`status`, `lint`, `resolve`) do not check, so `celigo config set api_token --profile ` still bootstraps a profile you mean to create. ## Which account a write targets Every command that writes to the account prints the target on stderr before the write, since celigo-cli 2026.9.1: ``` celigo: profile 'acme-sandbox' → api.integrator.io ``` Confirmation prompts carry the same label (`[profile 'acme-sandbox' → api.integrator.io] Delete flow 123? [y/N]`). Read that line — or run `celigo profile whoami` — before the first mutating command of a session. If it names the wrong account, stop: the machine-wide active profile may have been switched by `celigo profile use` in another terminal. Bind the session with `export CELIGO_PROFILE=`. See [Profiles & regions](/cli/getting-started/profiles.md#selecting-a-profile). ## `403 Forbidden` Token is valid but lacks the capability the request needs. Either broaden the token's scope in the UI, or switch to a profile whose token has admin access. ## `Read mode: blocked …` / `requires full mode` ``` Read mode: blocked PUT v1/flows/5f83a9b2c7d3e8f1a2b3c4d5. Switch with 'celigo config set mode operate' (or 'full'), or use a different profile. Command 'flows create' requires full mode. Current mode: read. Switch with 'celigo config set mode full' or use a different profile. ``` The profile's permission mode refused the command before any request left your machine. Follow the hint: `celigo config set mode operate` (or `full`) on that profile, or use a profile whose mode allows the action. See [Permission modes](/cli/getting-started/profiles.md#permission-modes). ``` Read mode (from CELIGO_MODE): blocked PUT v1/flows/5f83a9b2c7d3e8f1a2b3c4d5. Set CELIGO_MODE=operate or full (the environment variable overrides the profile's mode), or unset it. Current mode: read (from CELIGO_MODE). Set CELIGO_MODE=full (the environment variable overrides the profile's mode) or unset it. ``` When the refusal says `(from CELIGO_MODE)`, the environment variable set the mode and `celigo config set mode` changes nothing while it is exported. Unset it, or set `CELIGO_MODE=full` (or `operate`) for the session. Since celigo-cli 2026.9.1 the refusal names the source; earlier releases always hinted at `config set mode`. ## `404 Not Found` on a resource you know exists * Wrong base URL — the resource lives in a different region's tenant. * Wrong profile — check `celigo profile list`. * Custom-scoped token doesn't see the resource (the API returns `404 Not Found` to avoid leaking existence). ## `429 Too Many Requests` The HTTP client retries automatically — up to 3 times. Since celigo-cli 2026.9.1 it honors the server's `Retry-After` header (delay-seconds or an HTTP-date, capped at 60 seconds) instead of guessing with exponential backoff; without the header it backs off exponentially. `--verbose` prints each retry with its cause (`Retry 1/3 after 2000ms (HTTP 429, Retry-After)...`). If you're still being throttled: * Run with lower parallelism — serialize shell loops instead of `xargs -P`. For `pull`, `diff`, `push`, and `promote`, lower `--concurrency` (or `CELIGO_CONCURRENCY`; default 8). * Filter `jobs list` / `audit list` queries so they return fewer pages. * Batch writes at the source rather than looping one `POST` per record. See [Rate limits](https://developer.celigo.com/api/using-the-api/rate-limits) in the API section. ## `timed out after 30s` ``` note: PUT v1/flows/5f83a9b2c7d3e8f1a2b3c4d5 timed out after 30s — retrying up to 3 more times (a write that timed out may still have landed). ``` A request has a 30-second budget by default; long-running operations — invokes, previews, test runs, clones, `docs search`, and `file-definition-rules` submissions — get a 6-minute budget that matches the server's own ceiling. A request that times out is retried up to 3 times, and since celigo-cli 2026.9.1 the CLI says so once, verbose or not, before the first retry; `--verbose` names the retry cause (`timed out` or `HTTP 5xx`). Note the parenthesis: a write that timed out may already have landed, so check the account before repeating a create by hand. `push` and `promote` never resend a create's `POST` after a timeout for that reason (a later run adopts what landed instead of duplicating it). Retries exhausted on a timeout or a `5xx` exit `1` with the last error. Re-run with `--verbose` to see each attempt. ## `Error: self-signed certificate in certificate chain` Behind a corporate proxy with TLS interception. Point Node at your organization's CA bundle: ```bash export NODE_EXTRA_CA_CERTS=/path/to/corp-root-ca.pem ``` > ⚠️ **Never disable TLS certificate validation.** Do not set `NODE_TLS_REJECT_UNAUTHORIZED=0` — it disables cert checking account-wide in your shell and is a silent-failure vector. ## `EACCES` when installing globally On macOS/Linux without `sudo`, the default global prefix isn't writable. Either: ```bash # Use a user-local npm prefix mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH=~/.npm-global/bin:$PATH npm install -g @celigo/celigo-cli ``` Or use [nvm](https://github.com/nvm-sh/nvm) / [volta](https://volta.sh) — both handle the prefix for you. ## CLI says "A new version is available" The CLI auto-updates every four hours on startup. If auto-update failed or you want to force it: ```bash npm install -g @celigo/celigo-cli@latest ``` Suppress the check: `export CELIGO_NO_UPDATE=1`. ## Still stuck? * Re-run with `--verbose` — prints the underlying HTTP request/response (token redacted). Paste that into a support ticket along with `celigo --version`. * Community: [connective.celigo.com](https://connective.celigo.com). * Production incidents: [status.celigo.com](https://status.celigo.com). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.celigo.com/cli/using-the-cli/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.