Troubleshooting OSV-Scanner Scanning Issues: A Complete Guide to Fixing Common Errors

When osv-scanner fails with "no packages found" or extraction errors, verify your target paths contain supported lockfiles, ensure exclude patterns aren't filtering all files, and confirm at least one extractor plugin is enabled.

OSV-Scanner, Google's open-source vulnerability scanner, identifies security issues by parsing dependency lockfiles, SBOMs, and container images. When scans fail with cryptic errors like ErrNoPackagesFound or lockfile extraction failures, understanding the internal logic in pkg/osvscanner helps you resolve issues quickly. This guide provides concrete troubleshooting steps derived directly from the source code of the google/osv-scanner repository.

Common Causes of OSV-Scanner Scan Failures

No Packages Found Errors (ErrNoPackagesFound)

The error ErrNoPackagesFound originates in pkg/osvscanner/osvscanner.go:104-105 when the supplied path lacks recognizable lockfiles, SBOMs, or source files. This error also triggers when all files are filtered out by --exclude patterns or when the scanner runs in a directory without extractable content.

Lockfile Extraction Failures

When the scanner reports extraction failed on a specific lockfile, examine pkg/osvscanner/scan.go:86-92. Common causes include unsupported or corrupted lockfile formats, disabled plugins required for that file type, or permission issues preventing the scanner from reading the file.

SBOM Filename Validation Issues

Invalid SBOM filenames trigger errors at pkg/osvscanner/scan.go:90-93. Valid SBOMs must match recognized patterns like *.spdx.json or other suffixes registered by the SBOM plugin in the getPlugins function.

Network and Offline Mode Errors

Network-related failures stem from pkg/osvscanner/osvscanner.go:24-28 when the scanner cannot reach https://api.osv.dev for vulnerability queries. In offline environments, you must enable --compare-offline or the scan fails when attempting to initialize external accessors.

Missing Extractor Plugins

The error "at least one extractor must be enabled" originates from pkg/osvscanner/scan.go:22-25 and scan.go:98-107. This occurs when your plugin configuration contains only enrichers (metadata processors) without extractors (package parsers), causing countNotEnrichers to equal zero.

Container Image Scan Errors

Docker scanning failures in pkg/osvscanner/osvscanner.go:78-84 occur when DoContainerScan cannot export the image or when the tarball path is invalid. Images without extractable packages also trigger ErrNoPackagesFound through the imagehelpers.ExportDockerImage workflow.

Step-by-Step Troubleshooting for OSV-Scanner

Verify Target Paths and Debug Output

Start by confirming the scanner resolves paths correctly. The internal pathToRootMap function in pkg/osvscanner/scan.go:23-34 handles path resolution.

osv-scanner scan . --debug

Run this to reveal the absolute path the scanner attempts to scan. Typos or relative path issues become immediately visible in the output.

Check Extractor Plugin Configuration

Ensure at least one extractor is active. If you disabled defaults with --plugins-no-defaults, explicitly enable extractors:

osv-scanner scan --plugins-enabled=lockfile,sbom,directory .

If you encounter "at least one extractor must be enabled", verify your plugin set isn't enricher-only by checking the countNotEnrichers logic in scan.go:98-107.

Validate Lockfile and SBOM Formats

Lockfiles must use supported suffixes like package-lock.json, Gemfile.lock, or go.mod. SBOMs must match expected patterns (e.g., *.spdx.json). The plugin registration validates these patterns against the []string{"sbom"} configuration in the extractor setup.

Inspect Exclusion Patterns

Over-broad --exclude patterns parsed by parseExcludePatterns in pkg/osvscanner/scan.go:9-14 can hide all files, causing ErrNoPackagesFound. Temporarily remove exclude flags to isolate whether exclusion logic is the culprit.

Configure Network or Offline Mode

For online scans, ensure connectivity to https://api.osv.dev. For air-gapped environments, use --compare-offline with pre-downloaded databases:

osv-scanner scan --compare-offline --download-databases .

The scanner initializes a localmatcher instead of remote queries when initializeExternalAccessors runs in offline mode (osvscanner.go:24-33).

Handle Docker Image Scans

Verify the image exists locally (docker images). When using --image-archive, confirm tarball readability. Errors in DoContainerScan or imagehelpers.ExportDockerImage indicate export failures or unreadable image data.

Allow Scans Without Lockfiles

To prevent non-zero exit codes when no packages exist, use --allow-no-lockfiles. This flag is handled in cmd/osv-scanner/scan/source/command.go:142-147, allowing CI/CD pipelines to continue when scanning directories without dependencies.

Enable Debug Logging

Set the debug environment variable for detailed logs via the cmdlogger package:

export OSV_SCANNER_DEBUG=1
osv-scanner scan .

Practical Commands to Fix Scanning Issues

# Scan a directory with default plugins and debug output

osv-scanner scan ./my-project --debug

# Scan a specific lockfile, ignoring other files

osv-scanner scan --lockfile-path=go.mod --plugins-enabled=lockfile

# Scan a Docker image in offline mode with pre-downloaded DB

osv-scanner scan --image=my-app:latest \
                 --compare-offline \
                 --download-databases \
                 --allow-no-lockfiles

# Scan with custom exclusions (debug mode)

osv-scanner scan . \
  --exclude="**/test/**" \
  --exclude="**/*.gen.go" \
  --debug

# Force successful exit even when no packages are found

osv-scanner scan . --allow-no-lockfiles

# Scan an SBOM file (must match expected naming like *.spdx.json)

osv-scanner scan --sbom-path=dependencies.spdx.json

Key Source Code References

File	Purpose	Link
pkg/osvscanner/scan.go	Core scanning logic – path handling, plugin orchestration, error generation.	https://github.com/google/osv-scanner/blob/main/pkg/osvscanner/scan.go
pkg/osvscanner/osvscanner.go	High-level entry point (DoScan, DoContainerScan), external accessor init.	https://github.com/google/osv-scanner/blob/main/pkg/osvscanner/osvscanner.go
cmd/osv-scanner/scan/source/command.go	CLI command for source scanning, flag handling (--allow-no-lockfiles, --exclude).	https://github.com/google/osv-scanner/blob/main/cmd/osv-scanner/scan/source/command.go
cmd/osv-scanner/scan/image/command.go	CLI command for container-image scanning, image export handling.	https://github.com/google/osv-scanner/blob/main/cmd/osv-scanner/scan/image/command.go
internal/cmdlogger	Centralized logger used throughout the scanner – enables --debug output.	https://github.com/google/osv-scanner/tree/main/internal/cmdlogger

Summary

• Verify paths resolve correctly using --debug and inspect pathToRootMap logic in scan.go:23-34
• Ensure extractor plugins are enabled (not just enrichers) to avoid countNotEnrichers errors in scan.go:98-107
• Validate lockfile suffixes and SBOM naming patterns match the supported plugin registrations
• Remove over-broad --exclude patterns that trigger ErrNoPackagesFound in osvscanner.go:104-105
• Use --compare-offline and --download-databases for air-gapped scanning via localmatcher initialization
• Check Docker image export capabilities when DoContainerScan fails at osvscanner.go:78-84
• Apply --allow-no-lockfiles to permit successful exits when no packages are present, as implemented in command.go:142-147

Frequently Asked Questions

Why does osv-scanner report "no packages found" when lockfiles exist?

This occurs when --exclude patterns filter out all supported files, or when lockfiles use unsupported formats. Check pkg/osvscanner/osvscanner.go:104-105 for the ErrNoPackagesFound logic. Run with --debug to verify which files the scanner evaluates and whether exclusion patterns are hiding them.

How do I scan projects without internet access?

Enable offline mode with --compare-offline and pre-download vulnerability databases using --download-databases. The scanner switches to a localmatcher in initializeExternalAccessors (osvscanner.go:24-33) instead of querying OSV.dev APIs, allowing complete offline operation.

What causes "extraction failed" errors on specific lockfiles?

Extraction failures at pkg/osvscanner/scan.go:86-92 indicate corrupted files, unsupported formats, or permission issues. Verify the lockfile format is supported and the file is readable. Ensure the required plugin isn't disabled via --plugins-no-defaults, which would prevent parsing.

How can I prevent osv-scanner from failing when no packages are detected?

Use the --allow-no-lockfiles flag (handled in cmd/osv-scanner/scan/source/command.go:142-147) to return exit code 0 even when no packages are found. This is essential for CI/CD pipelines scanning directories that may not always contain dependency files, preventing false-negative build failures.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}