Scan Status Troubleshooting
Every scan job moves through a state machine: queued to running to a terminal status. This page explains what each terminal status means, common failure scenarios, and how to resolve them.
Scan statuses
Terminal statuses that appear once a scan finishes processing.
| Status | Meaning | What to do |
|---|---|---|
| done | Scan completed successfully. All stages finished without errors. | No action needed. View findings in the scan results page. |
| partial_failed | Scan partially completed but one or more stages failed. Some findings may still be available. | Check the scan events log for the specific stage that failed. See common scenarios below. |
| failed | Scan did not complete. No findings were produced. | Check the scan events log for the error. Verify that the uploaded file is a supported format and that the file path is correct. |
Common partial_failed scenarios
The most frequent reasons a scan ends in partial_failed and how to fix them.
The image has no recognizable package manager database. This happens with minimal base images (e.g., CentOS 7 minimal), scratch images, and distroless images. Deep mode requires an installed package inventory to operate.
- •Use --mode light instead of --mode deep. Light mode detects packages from the installed database only and does not require a full inventory.
- •Switch to a base image that includes a package manager (e.g., use alpine:3.20 instead of scratch).
The scanner could not detect any packages in the image. The image may be empty, use a custom or unsupported package format, or contain only static binaries with no metadata.
- •Verify the image is not empty or a scratch-based image with no installed packages.
- •Check if the package format is in the supported list below.
- •For static binaries, use the bin subcommand instead of container scanning.
File not found errors
When a scan fails immediately with only a few events logged.
If a scan shows failed status with only 2 events in the log, the scanner was unable to locate or read the uploaded file. This is usually caused by an incorrect file path or a missing file extension.
- •Verify the uploaded file path includes the correct extension (.tar, .tar.gz, .iso).
- •Check that the file was fully uploaded before the scan was triggered.
- •If using the API directly, confirm the S3 bucket and key match what was passed to the job.
Deep vs Light mode
Understanding when to use each scan mode.
--mode light- •Default scan mode
- •Detects packages from the installed package database only
- •Fast and accurate for most container images
- •Works with minimal images that have a package manager
- •No additional requirements beyond a recognized package DB
--mode deep- •Extended scan with YARA rules (if available)
- •Requires installed inventory to be present in the image
- •Fails with deep_mode_requires_installed_inventory if the image has no package DB
- •Use for thorough analysis of full OS images
- •Not recommended for scratch or distroless images
If you are unsure which mode to use, start with --mode light. It covers the vast majority of scanning use cases and will not fail on images that lack a full package inventory.
Supported package managers
ScanRook can detect and inventory packages from these ecosystems.
| Package manager | Distributions / ecosystems |
|---|---|
| RPM | RHEL, CentOS, Rocky, AlmaLinux, Fedora, Amazon Linux, Oracle Linux |
| dpkg | Debian, Ubuntu |
| APK | Alpine, Chainguard, Wolfi |
| npm | Node.js projects |
| pip | Python projects |
| Go modules | Go projects |
| Maven | Java projects |
| Cargo | Rust projects |
| RubyGems | Ruby projects |
| Composer | PHP projects |
| Hex | Elixir/Erlang projects |
| Pub | Dart/Flutter projects |
If your image uses a package format not listed above, the scanner will not be able to detect packages and the scan may end in partial_failed with zero findings.