This article walks through common problems when running a Vibgrate scan and how to resolve them using documented flags. It is for developers and CI engineers diagnosing unexpected scan behavior.
Overview
Most scan issues fall into a few buckets: a result that looks stale, a scan that includes the wrong files, a scan pointed at the wrong directory, or a pipeline that fails because of a gate. Each has a documented remedy.
A result looks stale
If you suspect the scan is returning cached data after a change, force a clean recompute:
vg scan --no-cache
If the clean run differs, the earlier result was cached; if it matches, the cache was not the cause.
The scan includes the wrong files
If generated, vendored, or build directories are inflating your results, exclude them:
vg scan --exclude dist
For a lasting fix, move exclusions into vibgrate.config.ts.
The scan runs against the wrong directory
Remember bare vg scans the current directory and you never append a trailing path. To target a different folder, use --cwd:
vg scan --cwd services/api
The pipeline fails unexpectedly
If CI fails a scan step, check whether a gate tripped. --fail-on fails on finding severity and --drift-budget fails when the DriftScore exceeds your ceiling. A non-zero exit from either is expected behavior, not a tool error. See the exit codes reference to map the exit status.
Clean up the output
If CI logs are noisy, add --quiet so only the essential output remains.
Related
See the scan performance and caching guide, the failing on severity guide, the exit codes reference, and the scan command reference.