grype: "could not determine distro" on a scratch-built base image
Fixes grype's distro detection failure on scratch or minimal base images. Use it when a scan dies because the image has no OS release metadata. Key trigger: a Dockerfile built FROM scratch with no os-release file.
TL;DR: Either add a minimal os-release file to the image declaring the distro you built against, or tell grype the distro explicitly with the distro flag at scan time. Scratch images ship no OS metadata, so grype cannot map OS packages to distro advisories without help. Giving it the distro explicitly unblocks the scan.
could not determine distro- Confirm the image really lacks OS metadata. Run
docker run --rm [IMAGE] cat /etc/os-release.
Expected: an error like "no such file or directory". If the file exists but is empty or malformed, the fix is the same.
- Option A, the durable fix: add a minimal os-release file in your Dockerfile that declares the distro and version your binaries were built against (ID and VERSION_ID fields, matching the real base, e.g. the alpine or debian release you compiled on). Rebuild the image.
Expected: the file is present in the rebuilt image and grype detects the distro on the next scan.
- Option B, the quick fix for a scan you need now: pass the distro explicitly, like
grype [IMAGE] --distro alpine:3.19, using the distro and version the image contents actually came from.
Expected: the scan runs to completion and OS packages are matched against that distro's advisories.
- Sanity-check the results after either fix.
Expected: findings reference the distro you declared. If you see a flood of implausible matches, the declared distro does not match what is actually in the image.
Use this when
- grype fails on an image built FROM scratch
- a minimal or distroless-style image has no os-release file
- you scan a directory or filesystem root that is not a full OS tree
Not for this skill when
- grype detects the distro but reports zero packages; that is a cataloging problem, not a detection problem
- the error names a specific corrupt file; fix the file instead
- you want grype to skip OS matching entirely; that is a different configuration choice, not this fix
Variant phrasings
grype cannot identify the Linux distribution in a scratch image
distro detection failed on a minimal container image
grype scan fails: no os-release in image
how to tell grype which distro a scratch image is based on
Why it happens
Grype maps OS packages to vulnerabilities through distro security advisories, and it picks the advisory set from the image's OS release metadata. FROM scratch means exactly that: an empty filesystem with your binaries and nothing else, so there is no metadata to read and the matcher has no advisory set to use. Declaring the distro by hand gives the matcher the mapping it needs.
Edge cases
- Declare the distro the binaries were actually built against, not the one you wish they were. Marking a glibc-linked image as alpine produces false matches because the advisory sets assume musl.
- If you copied libraries from multiple distros into one scratch image, no single distro flag is fully correct; note the mix in your scan documentation and treat OS findings as approximate.
- Some minimal images ship os-release in a nonstandard path; a symlink or copy to /etc/os-release is enough for detection.
- The flag is per-scan, so bake the os-release file into the image if the scan runs in CI where flags are easy to forget.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_ycZr-ZVN8ih82Ml09ZC7bg