What causes "No kernel found and --kernel was not provided." in firecracker-microvm/firecracker?

Pass the kernel explicitly: `python3 tools/sandbox.py --kernel /path/to/vmlinux` (inside the container, use a path under /firecracker or an existing mounted path).

firecracker-microvm/firecracker · error · SystemExit

No kernel found and --kernel was not provided.

Error message

No kernel found and --kernel was not provided.

What it means

At import time tools/sandbox.py scans the standard artifact locations with `kernels("vmlinux-*")`; if that yields nothing, the `--kernel` default is None. After argument parsing (and host-path translation), `args.kernel is None` means no kernel was discovered and none was supplied, so the script exits before creating any microVM. The rootfs/binary-dir handling cannot proceed without a guest kernel image.

Source

Thrown at tools/sandbox.py:111

parser.add_argument("--cpu-template-path", help="CPU template to use", type=Path)
parser.add_argument(
    "--boot-args", help="Kernel boot arguments", type=str, default=None, nargs="+"
)
parser.add_argument(
    "--debug", action="store_true", default=False, help="Use debug kernel"
)
parser.add_argument(
    "--gdb", action="store_true", default=False, help="Connect to Firecracker guest GDB"
)
args = parser.parse_args()
args.kernel = translate_host_path(args.kernel)
args.rootfs = translate_host_path(args.rootfs)
args.binary_dir = translate_host_path(args.binary_dir)
args.cpu_template_path = translate_host_path(args.cpu_template_path)
print(args)

if args.kernel is None:
    raise SystemExit("No kernel found and --kernel was not provided.")
if args.rootfs is None:
    raise SystemExit("No rootfs found and --rootfs was not provided.")

binary_dir = None
if args.binary_dir:
    binary_dir = Path(args.binary_dir).resolve()
elif args.gdb:
    # Build Firecracker with GDB feature if needed
    print("Building Firecracker with GDB feature...")
    binary_dir = build_tools.build_gdb()
    print("Build complete!")
else:
    binary_dir = DEFAULT_BINARY_DIR

cpu_template = None
if args.cpu_template_path is not None:
    cpu_template = json.loads(args.cpu_template_path.read_text("utf-8"))
vmfcty = MicroVMFactory(binary_dir)

View on GitHub (pinned to ea50487ec1)

Solutions

Pass the kernel explicitly: `python3 tools/sandbox.py --kernel /path/to/vmlinux` (inside the container, use a path under /firecracker or an existing mounted path).
Fetch a guest kernel into the expected artifacts location (e.g. download the Firecracker vmlinux binary for your target arch from the official release) so the `vmlinux-*` glob finds it and the default works again.
Re-run from the repository/tools directory so the artifact scan resolves the same paths it did when artifacts were downloaded.
Verify the kernel filename starts with `vmlinux-`; the discovery glob will not pick up differently named images.

Example fix

# before
python3 tools/sandbox.py
# SystemExit: No kernel found and --kernel was not provided.

# after
python3 tools/sandbox.py --kernel /firecracker/build/imgenv/vmlinux-6.1.x

Defensive patterns

Strategy: validation

Validate before calling

import sys
from pathlib import Path
from framework.artifacts import kernels

available = list(kernels("vmlinux-*"))
if not available and "--kernel" not in sys.argv[1:]:
    sys.exit("No vmlinux-* kernel found in the artifact directories. "
             "Download one or pass --kernel /path/to/vmlinux.")

Prevention

Download a vmlinux binary into the expected artifacts directory as part of dev-env setup, before first sandbox run.
Name kernel images with the vmlinux- prefix so automatic discovery finds them.
When scripting over sandbox.py, always pass --kernel explicitly instead of relying on discovery.

When it happens

Trigger: Running `tools/sandbox.py` in a fresh checkout or container where no vmlinux-* binary has been fetched into the artifacts directory, without passing `--kernel`. Also triggered when the artifacts glob runs from a working directory where the kernel directory is not reachable, so the scan silently returns empty.

Common situations: First-time setup of the Firecracker dev environment: kernels are not part of the repo and must be downloaded separately. Developers who cleaned build artifacts, moved the checkout, or ran the script with an unexpected cwd hit this. The error also appears when the downloaded kernel has a different naming pattern that does not match `vmlinux-*`.

Related errors

AI-assisted analysis of firecracker-microvm/firecracker@ea50487ec1 (2026-08-16). Data as JSON: /api/errors/b90bc31c78a4c9e6. Report an issue: GitHub.