Troubleshooting
The problems people run into most often with the CLI, and how to fix each one. For everything else, see Troubleshooting & FAQ.
Quick reference
| Symptom | Fix |
|---|---|
| HTTP 401 | Run apivault login |
VAULT_KEY_REQUIRED | Provide the vault key via --vault-key, APIVAULT_KEY, or config |
Secrets not loading in run | Check the environment name matches the keys in the vault (keys list) |
.env files missing after run | Run apivault env restore |
PowerShell strips -- | The CLI falls back to the remaining arguments; or save the command as run.command |
Signed out or token expired
A device token lasts 90 days. Once it lapses, commands report the date it expired, and running apivault with no arguments says the token has expired rather than that you never signed in. Sign in again to get a fresh one:
apivault login
apivault whoami shows how long the current token has left.
Vault key required or rejected
Projects in custom encryption mode need the vault key for any command that encrypts or decrypts. Pass it with --vault-key, set APIVAULT_KEY, or save it with apivault config set vaultKey. Without a terminal to prompt on — in a pipeline, for example — one of these must be set.
After 10 incorrect vault keys in 15 minutes the CLI reports how long to wait, for example “try again in 7m”. Wait that long rather than retrying straight away. See custom vault key.
Secrets missing from run
apivault run loads only the keys in the chosen environment. Compare the environment it used with the keys that exist, and check the project:
apivault projects current apivault config get run.env apivault keys list
Errors under a service token
A token that is expired, revoked, or blocked by its IP allowlist says so exactly. A bare APIVAULT_TOKEN was not recognised means the value never matched a token at all — usually a truncated copy or a secret set on the wrong repository. Some commands, such as projects list and logs, are not available to service tokens at all; see which CLI commands work.
PowerShell and the -- separator
PowerShell can drop the -- that separates apivault run's options from your command. The CLI then uses the remaining arguments as the command, so this usually still works. If your command has options of its own that the CLI might take as its own, save the command instead and run it without arguments:
apivault config set run.command "npm run dev -- --port 4000" apivault run --env Development