Troubleshooting

Exact CLI error messages, what actually causes them, and the fastest fix — from stale contexts to rate limits.

Real failure modes, matched to the exact message the CLI prints. Each section starts with the error, explains the cause, and gives the fix.

Invalid or expired token

Invalid or expired token

Printed by varsafe login --token when the API rejects the token. Two distinct causes:

1. The token is actually invalid — it was revoked, rotated (rotation invalidates the old token immediately), or mistyped. Create or copy a fresh token from the dashboard’s API Tokens page.

2. The token is fine, but your saved context points at a team the token cannot access. The CLI sends the active team from your saved context with every request. API tokens are scoped to one team — if a leftover context references a different team, a perfectly valid token is rejected. This bites when you switch between a personal login and a CI token on the same machine.

Fix by clearing the stale context, then retry:

# If a .varsafe file exists in the directory (or any parent), remove it —
# it takes priority over the global context
rm ./.varsafe

# Then clear the global saved context
varsafe use --clear

varsafe login --token "$VARSAFE_TOKEN"

varsafe login opens your browser to authenticate. On headless machines, over SSH, or when the browser session gets stuck, use one of the non-browser paths:

# Email/password prompt instead of the browser
varsafe login --no-browser

# API token, prompted with masked input (not visible in shell history)
varsafe login --token-prompt

# API token from an environment variable
VARSAFE_TOKEN=vs_at_... varsafe login

The browser flow expires after a few minutes if it is not completed — if it times out or the confirmation code expires, rerun the login with one of the options above.

`Not signed in`

Not signed in
Run `varsafe login` to authenticate, or set VARSAFE_TOKEN env var for CI/CD

No stored session and no token in the environment. Run varsafe login, or export VARSAFE_API_TOKEN (alias: VARSAFE_TOKEN) — every command picks the env var up without a login step.

`varsafe list` shows nothing, or the wrong secrets

You are looking at a different project or environment than you think. The CLI resolves context in this order: command flags (-p/-i/-e) → local .varsafe file → global saved context. Check and fix:

# Show the current saved context
varsafe use

# Re-select interactively
varsafe use -p my-api -e development

# Or bypass context entirely for one command
varsafe list -p my-api -e development

If a teammate deleted the project or environment your context references, commands fail with:

Project not found. It may have been deleted. Run `varsafe use` to update.

`Project is required` in scripts and CI

Project is required. Use -p <project> or -i <project-id> to specify.

In a non-interactive session (CI, cron, piped output) the CLI cannot prompt, so the project and environment must come from flags or a saved context. Pass -i with the project ID for rename-proof automation — see CI/CD Pipelines.

Install fails on Linux ARM64

Linux ARM64 is not supported yet

The install script detects the platform and exits on linux-arm64 — there is no prebuilt binary for it yet. Supported platforms: Linux x64, macOS x64, and macOS ARM64 (Apple Silicon). On an ARM Linux host (Raspberry Pi, Graviton, ARM CI runners), run varsafe from an x64 container or machine instead.

Pointing the CLI at a self-hosted API

By default the CLI talks to https://api.varsafe.dev. To target a self-hosted or staging instance, either:

# Per-invocation or CI: env var takes priority over everything
VARSAFE_API_URL=https://varsafe.internal.example.com varsafe whoami

# Or persist it at login time
varsafe login --api-url https://varsafe.internal.example.com

If commands fail with Cannot connect to server, verify the URL is reachable from the machine (curl the API host) — the CLI falls back to cached project/environment data where it can, but secret fetches need a live connection.

Rate limits

The API rate-limits requests and answers 429 with a Retry-After header when a client exceeds its budget. If a script hits limits, space out calls or batch work — one varsafe run per deploy instead of a varsafe get per variable.

Where to see what happened

Every secret read, write, export, and login is recorded in the append-only audit trail: dashboard → Audit Log. Filter by actor, action, or date to reconstruct exactly what a token, teammate, or AI agent did — useful for confirming whether a “missing” secret was deleted, renamed, or never existed. See the Dashboard Guide.

Still stuck?

VARSAFE_DEBUG=1 makes the CLI write diagnostic details to its debug log
Check the exact error message against this page’s headings — the CLI prints stable, grep-able messages
Contact support with the command, the full error output, and your CLI version (varsafe --version)