Troubleshooting
SBOMFlow errors carry a stable code, a cause, a concrete fix, and a docs link. You can also read any error offline:
sbomflow help error E001Common first-run issues
| Symptom | Likely cause | Fix |
|---|---|---|
[E001] Target directory not found | wrong path | pass an existing product directory; try sbomflow quickstart . |
[E002] Target path is not a directory | pointed at a file | point at a directory; import a single SBOM with --import-sbom |
[E003] Output path is not a directory | --output is a file | choose a directory path (created if missing) |
[E010] Malformed or unknown-key configuration | bad sbomflow.yaml | sbomflow validate-config <file> then sbomflow doctor . |
sbomflow: command not found | entry point not on PATH | ensure your Python scripts dir is on PATH; re-run python -m pip install . |
findings show CVE-SAMPLE-* | offline sample feed | that is the labelled non-real default; enable a real source (e.g. --use-osv) |
See the full error reference and exit codes.
Optional tools reported as "skipped"
Some importers use external tools. When a tool is not installed, SBOMFlow reports it as skipped / available later — it does not fail the run and never installs anything for you.
CI interpretation
0— success or informational gate.1— an enforced release gate blocked the run (a policy decision, not a crash).2— usage, input, IO, or config error (see the error code).3— init refused / bundle verification failed.4— structural validation failure.5— strict warnings-as-errors matched.
Proxies, TLS, timeouts
Network actions are opt-in. If an enabled online lookup fails behind a proxy or TLS-inspecting gateway, the failure is surfaced as a warning (never silently ignored) and does not corrupt already-written evidence. Prefer offline snapshot files (--nvd-file, --kev-file, --epss-file) in restricted networks.
Deterministic output differs between runs
Provide a fixed --as-of timestamp for fully reproducible runs, and compare with sbomflow validate / compare-releases.