Troubleshooting Scans

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.