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

> Fix osv-scanner scanning issues like no packages found or extraction errors. Learn troubleshooting steps for lockfiles, exclude patterns, and extractor plugins.

- Repository: [Google/osv-scanner](https://github.com/google/osv-scanner)
- Tags: how-to-guide
- Published: 2026-04-25

---

**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.

```bash
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:

```bash
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`](https://github.com/google/osv-scanner/blob/main/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:

```bash
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:

```bash
export OSV_SCANNER_DEBUG=1
osv-scanner scan .

```

## Practical Commands to Fix Scanning Issues

```bash

# 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`](https://github.com/google/osv-scanner/blob/main/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`](https://github.com/google/osv-scanner/blob/main/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`](https://github.com/google/osv-scanner/blob/main/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`](https://github.com/google/osv-scanner/blob/main/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.