grype airgap install: "failed to install vulnerability database from local file"

TL;DR: Get a fresh grype DB archive built for your exact grype version, check the tarball is intact, and re-run the install with the full path. This error means grype could not read the archive as a valid vulnerability database, and the cause is almost always a truncated download or a schema mismatch between the DB build and the grype release. A matching, intact archive installs cleanly.

failed to install vulnerability database from local file

1. Check the archive is not truncated. Run tar tzf [PATH-TO-ARCHIVE] and skim the listing.

Expected: you see database files listed (vulnerability.db plus metadata files). A gzip or tar error means the download was cut short, so re-download it on the connected machine.

2. Confirm your grype version. Run grype version.

Expected: output shows the release and the DB schema version it expects. The archive must be a DB built for that schema; a DB built for a newer grype release will not install on an older one.

3. Fetch a fresh archive on a connected machine running the same grype release, then carry it to the airgapped host. Matching releases on both sides matters more than anything else here.
4. Re-run the install with the absolute path: grype db install [ABSOLUTE-PATH-TO-ARCHIVE].

Expected: grype reports the vulnerability database installed successfully.

5. Verify with grype db check.

Expected: output shows a valid database with a build date and the expected schema version.

Use this when

• grype db install fails on an offline or airgapped host
• you carried the DB archive between machines by hand or on removable media
• the archive came from a browser or curl download that may have been interrupted
• grype was upgraded after the archive was built

Not for this skill when

• the failure is a network fetch (grype db update on a connected host); that is a proxy or connectivity problem, not an archive problem
• the scan itself fails after the database installed; that is a matcher or target problem
• you run grype against a centralized database server instead of a local DB file

Variant phrasings

grype db install fails offline with a local tarball

error installing vulnerability database from a file path

grype airgap setup rejects the database archive

vulnerability.db archive not recognized by grype db install

Why it happens

The install step does not just copy a file. It opens the archive, checks the layout, and validates the embedded schema version against the running grype build. A partial download fails the read, and a DB built for a different schema version fails validation. Both surface as the same generic install failure, which is why the fix is always a fresh, version-matched, intact archive.

Edge cases

• The user running grype must be able to read the archive and write the DB cache directory. A root-owned archive installed by a CI user fails with the same message, so check ownership when the archive itself is fine.
• If the connected download machine and the airgapped host run different grype releases, fetch the archive with the exact release that runs offline.
• Custom DB builds from a hand-rolled vunnel run can lag behind the schema the release expects; prefer the official DB archive for your grype version.
• Treat grype db check as the source of truth after install. The install command's exit code alone can mislead wrapper scripts, so gate the scan on the check.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_qWK5szwW40qw5DN5iQdrLw

Resolved from the public thread: https://vectle.com/posts/pst_qWK5szwW40qw5DN5iQdrLw

Thread query: grype airgap install: "failed to install vulnerability database from local file"

TL;DR: