Troubleshooting & FAQ

Common problems running Gadriel Code, and how to resolve them. If you don't find your issue here, gadriel code doctor and the exit-code reference are good next stops.

Related pages: Reports & outputs · Compliance reporting · SBOM.

OSV "coverage DEGRADED"

Symptom. A scan prints a warning like:

[gadriel] WARNING: OSV shard sync failed for all N ecosystems; CVE detection
DEGRADED for this scan. Re-run 'gadriel code policies --osv' or pre-warm the
snapshot to fix.

and findings.json shows coverage_status: degraded and osv_synced: false.

Cause. SCA vulnerability detection downloads per-ecosystem OSV snapshots. To protect against runaway or hostile downloads, each language ecosystem shard is capped at 64 MiB (OS/distro shards get a larger 768 MiB cap, and the monolithic snapshot has a 512 MiB cap). If a shard's all.zip exceeds the cap while streaming, it is rejected before being written, that ecosystem's CVEs are missing from the scan, and coverage is marked DEGRADED. The npm shard is the one most likely to bump against the 64 MiB language cap, so npm-heavy repos are the usual trigger.

If only some shards fail, the scan proceeds with partial coverage (the failed ecosystem's CVEs silently absent). If every shard fails, you get the DEGRADED banner above. GVL rules that require OSV data are skipped, and the scan verdict gets a · coverage DEGRADED suffix.

Fixes.

Pre-warm the snapshot — fetch the OSV data once, outside the scan:

bash
gadriel code policies --osv          # auto-detects ecosystems from your manifests
gadriel code policies --osv --force  # force a re-fetch

Scan a smaller / specific ecosystem set — avoid the oversized shard:

bash
gadriel code scan --osv-ecosystems=pypi        # single ecosystem
gadriel code scan --osv-ecosystems=pypi,cargo  # explicit list

(--osv-ecosystems also accepts auto, the default, and all.)

Accept DEGRADED for non-SCA runs — if you don't need CVE data this run, skip OSV entirely:

bash
gadriel code scan --no-osv
gadriel code scan --offline          # alias for --osv-auto-sync=no

License / auth errors (exit code 7)

Symptom. A command exits with code 7 and a banner suggesting gadriel auth login / gadriel auth refresh / gadriel auth status.

Cause. Exit 7 is the license gate. It fires when there is no cached license token, or the token has been revoked, or it has expired past the offline-grace window. The gate runs on most commands — including gadriel code scan — but is exempt for auth, version, completion, config, doctor, telemetry, hooks, and code mcp.

Fix.

bash
gadriel auth login     # obtain / refresh a token
gadriel auth status    # inspect current token state
gadriel auth refresh   # renew an expiring token

PREFLIGHT_OFFLINE=1 does not bypass exit 7. The PREFLIGHT_OFFLINE (and PREFLIGHT_LOCAL) environment variable only skips the online authentication check; it does not satisfy the license gate for a release build. If you are hitting exit 7, you need a valid token via gadriel auth login, not offline mode. (PREFLIGHT_OFFLINE=1 is still the right lever for avoiding network calls on commands that only require online auth, which surfaces as exit 2, not 7.)

"gadriel is already initialized"

Symptom.

gadriel is already initialized in <dir> (found a non-empty .security/…).
Re-run with `--upgrade` to merge new settings, `--add-missing` to add only
missing files, or `--force` to overwrite.

Cause. gadriel code init refuses to run in a directory that already contains Gadriel-owned files, to avoid clobbering your customizations.

Fix — pick the flag that matches your intent:

Flag	Behavior
`--upgrade`	Merge new settings into existing files; preserve your customizations.
`--add-missing`	Add only missing files/keys; never modify anything that exists.
`--force`	Overwrite all Gadriel-owned files.

bash
gadriel code init --upgrade

"no calibration table found"

Symptom. gadriel code policies (without --osv) exits with:

no calibration table found. Set GADRIEL_CALIBRATION_TABLE to a
calibration-table.json produced by 'gadriel-fp-benchmark calibration-build',
or ship one to '<store>/calibration-table.json'.

or gadriel code learn status reports calibration table: not loaded.

Cause. The calibration table is an optional feature that tunes finding confidence. It is additive — scans and learn status work fine without it, and a finding with no calibration entry is simply left unadjusted.

Fix (or ignore).

Ignore it. If you don't need confidence calibration, don't run the non---osv policies path. Scanning is unaffected.
Ship a table. Gadriel resolves the table in this order:
1. the path in the GADRIEL_CALIBRATION_TABLE environment variable;
2. <per-machine store>/calibration-table.json;
3. the repo-local dev copy under the fp-benchmark crate.
Produce a table offline with gadriel-fp-benchmark calibration-build, then run gadriel code policies to seed it into the store.

Checking integration parity: `gadriel code doctor --platform`

To verify that a given host/IDE integration has the capabilities Gadriel expects, run:

bash
gadriel code doctor --platform cursor

Supported --platform values: claude-code (the native reference platform), cursor, windsurf, copilot, codex, jetbrains, claude-desktop, chatgpt, ai-studio.

The command prints a capability parity table for that platform: which MCP tools are available, whether real-time hooks are supported, whether context/rules injection works, the content byte cap, and confirmation that the CI gate and audit log (which are platform-agnostic) are present. It also surfaces version-gate notes — e.g. that a particular integration hook requires a minimum CLI version, or that a desktop app must be installed.

There is also a separate top-level gadriel doctor (no code) for general environment diagnostics. The integration-parity checker is gadriel code doctor --platform <name>.

Where logs and artifacts live

Scan artifacts live under .security/ at the repo root — findings, reports, SBOM, compliance, and the operational store. See the full layout in Reports & outputs.
Audit log: .security/audit-log.jsonl (append-only NDJSON).
Per-machine store (OSV snapshots, calibration table, cross-repo state): ~/.gadriel/store by default, overridable with the GADRIEL_STORE_DIR environment variable.
Diagnostic logging goes to stderr (stdout is kept clean for JSON/SARIF/OCSF output) and is controlled by the standard RUST_LOG environment variable. Defaults when unset: info normally, debug under --verbose. For example:
```
bash
RUST_LOG=debug gadriel code scan
```

Exit-code reference

Code	Meaning
0	Success.
1	Security gate tripped — findings at or above the `--fail-on` threshold. This is what CI/hooks test for to block a change.
2	CLI / tooling error — I/O, config, usage, a scanner failure, or "not authenticated" for online-auth commands. Also the code clap uses for argument-usage errors.
3	Feature not yet available (a stubbed verb), or a fatal render failure in the `report` command.
7	License-gate failure — no cached token, revoked, or grace-exceeded. See License/auth errors.

Notes:

The gadriel code scan --fail-on hook contract is specifically: 0 = clean, 1 = threshold tripped, 2 = tooling error. --verdict-exit-zero collapses a verdict-driven non-zero to 0 while genuine errors still exit non-zero.
The report command has its own verdict codes under --fail-on verdict (1 = PARTIAL, 2 = FAIL, 3 = fatal render); see Compliance reporting.
Codes 4, 5, and 6 are unused.