# 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 (US token against EU URL, or vice versa).

Inspect the active config:

```bash
celigo config show
celigo profile list
```

Rotate the token with `celigo config set api_token <new>` and retry. See [Authenticate](/cli/setup/authenticate.md).

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

## `404 Not Found` on a resource you know exists

* Wrong base URL (EU resource on US tenant, or vice versa).
* Wrong profile — check `celigo profile list`.
* Custom-scoped token doesn't see the resource (the API returns `404` to avoid leaking existence).

## `429 Too Many Requests`

The HTTP client retries automatically with the server-supplied `Retry-After`. If you're still being throttled:

* Run with lower parallelism — serialize shell loops instead of `xargs -P`.
* 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.

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

**Do not** set `NODE_TLS_REJECT_UNAUTHORIZED=0` — that 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: 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:

```
GET https://developer.celigo.com/cli/reference/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.