Troubleshooting

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

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

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

Get help

Email help@vigilbase.com or visit vigilbase.com/help.