# Troubleshooting

> Check connectivity with vigilbase doctor and fix common CLI problems with sign-in, credentials, certificates and the local Cloudflare Checkup.

Source: https://docs.vigilbase.com/tools/cli/troubleshooting

Start with `vigilbase doctor`. It runs three checks on their own and exits 1 if any fails:

| Check | What it tests |
| --- | --- |
| `publicApi` | `GET https://vigilbase.com/api/v1/agent/tools` |
| `one` | Your session: Vigilbase One when you are signed out, or the Identity issuer when you are signed in |
| `signIn` | Whether your saved sign-in works, including a refresh if one is due |

```terminal
$ vigilbase doctor --json
```

DNS, TLS, connection and timeout failures name the endpoint and the cause. Use `--base-url`, `--one-url`, `--auth-url` and `--timeout` to check other environments.

## Common problems

:::accordion
### Signing in isn't supported on Windows yet
The CLI cannot yet protect credential files on Windows, so `login`, `whoami`, the Vigilbase One commands and the One-only scans stop with code `SIGN_IN_UNSUPPORTED`. Public tools, `doctor`, `describe`, `skill`, `badge` and `cloudflare-checkup` work on Windows.

### This command needs a Vigilbase One sign-in
The command uses Vigilbase One. Run `vigilbase login`. Public scans (`headers`, `email`) never need it.

### Unknown command "cloudflare-checkup"
An older global install (0.1.x) is answering. Update it with `npm install -g @vigilbase/cli@latest`, or run `npx @vigilbase/cli@latest cloudflare-checkup` once. `vigilbase --version` shows which version answers.

### yarn dlx or pnpm dlx runs an older version
Yarn 4.15 and later and pnpm 11 and later skip releases published in the last 24 hours by default. Use `npx @vigilbase/cli`, or wait a day.

### … is a symbolic link, or … must have mode 0700
The CLI refuses a config path with a symbolic link, a parent that other users can write to, or a config directory without mode `0700`. Run the `chmod` the error names, or point `VIGILBASE_CONFIG_DIR` at a private directory of its own, for example `export VIGILBASE_CONFIG_DIR="$(cd ~ && pwd -P)/.vigilbase"`. Don't use a synced folder or a dotfiles repository.

### Your saved sign-in was ended by Vigilbase Identity
You signed out in the browser, or the session ended. Run `vigilbase login`.

### A previous vigilbase command was interrupted while it held …
A command was stopped while refreshing your sign-in. Run `vigilbase login`.

### fetch failed or SELF_SIGNED_CERT_IN_CHAIN
On Node 22.19+ and 24.5+ the CLI trusts your operating system's certificates. On an older Node 22, run with `NODE_OPTIONS="--use-system-ca"`, or set `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` for a private CA. Do not set `NODE_TLS_REJECT_UNAUTHORIZED=0`.

### Requests ignore my proxy
Node's built-in fetch ignores `HTTP_PROXY` and `HTTPS_PROXY` unless `NODE_USE_ENV_PROXY=1` is set (Node 22.21+ or 24.5+).

### UNEXPECTED_REDIRECT
The CLI never follows redirects. Set `--base-url` (or the matching option) to the origin named in the error.

### Rate limited (exit code 2)
The hourly scan quota is used up. Wait for the delay in the message (`retryAfterSec` in JSON).
:::

## Cloudflare Checkup errors

The local [Cloudflare Checkup](https://docs.vigilbase.com/tools/cli/cloudflare-checkup-cli) prints a stable code and a hint. Most fixes are to run the same command again.

| Code | Fix |
| --- | --- |
| `NODE_UNSUPPORTED` | Install Node.js 22.18 or newer. |
| `LOCAL_MODE_DISABLED` | Local checkups are off. Run the checkup in your browser at [vigilbase.com/tools/cloudflare-checkup](https://vigilbase.com/tools/cloudflare-checkup). |
| `CLI_UPGRADE_REQUIRED` | Run `npx @vigilbase/cli@latest cloudflare-checkup`. |
| `CF_NOT_FOUND`, `CF_WRONG_BINARY` | Run the command again in a terminal and let it install `cf` (add `--yes` without a terminal). |
| `CF_AUTH_REQUIRED` | Run the command again in a terminal to sign in, or set a valid read-only `CLOUDFLARE_API_TOKEN`. |
| `CF_PERMISSION_DENIED` | Your Cloudflare login cannot read the zones. Check its permissions. |
| `CF_RATE_LIMITED` | Wait 5 minutes, then try again; add `--max-requests-per-5min 600` if it repeats. |
| `ACCOUNT_SELECTION_REQUIRED` | Run in a terminal to choose, or add `--account-id`. |
| `ACCOUNT_TOO_LARGE` | Local collection supports up to 100 zones. Use the browser checkup. |
| `EMAIL_INVALID` | Use your work email. Personal and disposable addresses are refused. |
| `EMAIL_CODE_INVALID` | Five codes were wrong. Run the command again for a new code. |
| `VERIFICATION_EXPIRED`, `SESSION_EXPIRED` | Run the command again. After a collection, upload the saved file with `submit`. |
| `SNAPSHOT_STALE` | Snapshots are accepted for 24 hours. Collect a fresh one. |
| `SNAPSHOT_TOO_LARGE` | Use the browser checkup. |
| `VIGILBASE_RATE_LIMITED` | Wait as long as the error says. vigilbase.com allows one checkup every 8 minutes and 3 codes an hour per address. |
| `CANCELLED` | You pressed Ctrl-C. Nothing was uploaded. |

The full list ships with the CLI in [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.10/files/LOCAL.md).

## Get help

Email help@vigilbase.com or visit [vigilbase.com/help](https://vigilbase.com/help).