firecracker-microvm/firecracker · error · SystemExit

No rootfs found and --rootfs was not provided.

Error message

No rootfs found and --rootfs was not provided.

What it means

tools/sandbox.py scans for `*.ext4` disk images at import time and derives a default rootfs via `pick_default_rootfs` (preferring amazonlinux-*, then ubuntu-*, then any match). If no ext4 disk is found, `default_rootfs` is None; when `--rootfs` is also absent, `args.rootfs is None` and the script exits, because a Firecracker microVM cannot boot without a guest root filesystem.

Source

Thrown at tools/sandbox.py:113

    "--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)

if args.debug or args.gdb:

View on GitHub (pinned to ea50487ec1)

Solutions

1. Pass the rootfs explicitly: `python3 tools/sandbox.py --rootfs /path/to/rootfs.ext4`.
2. Download an ext4 guest image (e.g. the Ubuntu or AL2023 rootfs used by Firecracker tests) into the artifacts directory so the `*.ext4` glob discovers it and amazonlinux-/ubuntu- defaults apply.
3. If your image is .raw or another format, convert or rename it to .ext4 so discovery finds it.
4. Re-run from the expected working directory so the artifacts scan uses the same root as the download scripts.

Example fix

# before
python3 tools/sandbox.py --kernel /firecracker/build/imgenv/vmlinux-6.1.x
# SystemExit: No rootfs found and --rootfs was not provided.

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

import sys
from framework.artifacts import disks

available = list(disks("*.ext4"))
if not available and "--rootfs" not in sys.argv[1:]:
    sys.exit("No *.ext4 rootfs found. Download one or pass --rootfs /path/to/rootfs.ext4.")

When it happens

Trigger: Running `tools/sandbox.py` in an environment where no `*.ext4` rootfs image has been downloaded into the artifacts directory and no `--rootfs` flag is given. Also occurs when the only disk images present have extensions other than .ext4 (e.g. .raw, .qcow2), since the discovery glob and `disks("*.ext4")` filter strictly.

Common situations: Fresh dev-container or CI environment where rootfs images were never fetched; artifacts directory cleaned or relocated; developer assumed a squashfs/raw image would be auto-detected. Like the kernel error, this is a missing-artifact setup problem, not a Firecracker runtime failure.

Related errors

• No kernel found and --kernel was not provided.
• {p} not found in container and not under host workspace {hos
• version does not match vX.Y.Z
• VhostUserBlock does not support snapshotting yet
• VhostUserBlock does not support snapshotting yet

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