This reference groups the kinds of problems the Vibgrate CLI surfaces and points you to the fix for each. It is for developers reading an unexpected message in the terminal or CI logs. For the numeric side, see the Exit Codes reference.
Command not found
If your shell reports that vg is not found, the install did not complete or is not on your PATH. Open a new terminal, reinstall @vibgrate/cli, or use the no-install form:
npx @vibgrate/cli scan
See the install troubleshooting article.
Nothing to analyze
If a scan reports no projects, detection found no recognizable manifests in the scanned tree, or an exclusion hid them. Confirm the directory and exclusions:
vg scan --cwd path/to/project
See the no-projects-detected article.
Gate failures
When a build fails after a clean scan, a quality gate likely fired by design. These are expected outcomes of:
vg scan --fail-on error
vg scan --drift-budget 60
This is not an error in the CLI — it is the gate doing its job. Read the exit code to confirm.
Authentication and upload errors
Messages during vg push usually mean a credential problem. Re-authenticate, or in CI use a DSN token:
vg logout
vg login
vg dsn create
See the auth troubleshooting article.
Network and offline
If a command waits on or fails to reach the network, confirm whether it needs the network at all. Scans run locally; uploads do not. Force local behavior to isolate the issue:
vg scan --offline
Stale code-map results
If graph queries look wrong, the map may be stale. Check and rebuild:
vg status
vg build
Related
- Exit Codes reference
- Troubleshooting install, auth, and no-projects articles
- The
vg scanandvg pushcommand pages