Troubleshooting
Quick answers for frequent issues.
For any CLI problem, follow the same sequence first: run the command with --help to confirm syntax, retry with -v when available for more detail, then verify profile and authentication state with uvx v8x whoami.
v8x Authentication Fails
Before debugging environment issues, confirm the login command and its available flags:
uvx v8x login --help
uvx v8x login # complete device flow in browser
If the terminal shows a "loop": verify network access to OIDC URL and that system clock skew < 60s.
Success looks like this: login completes once, returns control to the shell, and follow-up commands stop asking you to authenticate again immediately.
Expired Token
uvx v8x whoami # triggers refresh if possible
uvx v8x login # re-authenticate if still failing
Success looks like this: uvx v8x whoami returns a valid identity and token status instead of an auth failure.
Profile Not Found
Use uvx v8x profile --help if you need to confirm the correct profile subcommands.
uvx v8x profile list
uvx v8x profile create dev --activate
uvx v8x profile use dev
Success looks like this: the expected profile appears in the list and the active profile matches the environment you meant to target.
JSON Output / Parsing Errors
Ensure you used --json before piping to jq:
uvx v8x cluster list --json | jq '.clusters | length'
Success looks like this: the command outputs valid JSON and jq no longer fails on plain text table output.
Network / API Errors
- Add
-vfor debug logs - Confirm configured endpoints
- Run the failing subcommand with
--helpfirst if you are not sure the flags are valid for your current CLI version
Token Cache Corruption
Remove token file (path may differ by install) then re-login:
rm ~/.config/v8x/tokens/<profile>.json 2>/dev/null || true
uvx v8x login
Rate Limits / Throttling
Retry after brief backoff; excessive rapid polling may be limited.
Still Stuck?
Open an issue including: command run, abbreviated error, Python version, profile name (not tokens).