{"record":{"id":"b725d31011cdd3d1","repo":"firecracker-microvm/firecracker","slug":"no-rootfs-found-and-rootfs-was-not-provided","errorCode":null,"errorMessage":"No rootfs found and --rootfs was not provided.","messagePattern":"No rootfs found and --rootfs was not provided\\.","errorType":"exception","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"tools/sandbox.py","lineNumber":113,"sourceCode":"    \"--boot-args\", help=\"Kernel boot arguments\", type=str, default=None, nargs=\"+\"\n)\nparser.add_argument(\n    \"--debug\", action=\"store_true\", default=False, help=\"Use debug kernel\"\n)\nparser.add_argument(\n    \"--gdb\", action=\"store_true\", default=False, help=\"Connect to Firecracker guest GDB\"\n)\nargs = parser.parse_args()\nargs.kernel = translate_host_path(args.kernel)\nargs.rootfs = translate_host_path(args.rootfs)\nargs.binary_dir = translate_host_path(args.binary_dir)\nargs.cpu_template_path = translate_host_path(args.cpu_template_path)\nprint(args)\n\nif args.kernel is None:\n    raise SystemExit(\"No kernel found and --kernel was not provided.\")\nif args.rootfs is None:\n    raise SystemExit(\"No rootfs found and --rootfs was not provided.\")\n\nbinary_dir = None\nif args.binary_dir:\n    binary_dir = Path(args.binary_dir).resolve()\nelif args.gdb:\n    # Build Firecracker with GDB feature if needed\n    print(\"Building Firecracker with GDB feature...\")\n    binary_dir = build_tools.build_gdb()\n    print(\"Build complete!\")\nelse:\n    binary_dir = DEFAULT_BINARY_DIR\n\ncpu_template = None\nif args.cpu_template_path is not None:\n    cpu_template = json.loads(args.cpu_template_path.read_text(\"utf-8\"))\nvmfcty = MicroVMFactory(binary_dir)\n\nif args.debug or args.gdb:","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/firecracker-microvm/firecracker/blob/ea50487ec11602100b90ed63f85fe00bd30fbde8/tools/sandbox.py#L95-L131","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass the rootfs explicitly: `python3 tools/sandbox.py --rootfs /path/to/rootfs.ext4`.","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.","If your image is .raw or another format, convert or rename it to .ext4 so discovery finds it.","Re-run from the expected working directory so the artifacts scan uses the same root as the download scripts."],"exampleFix":"# before\npython3 tools/sandbox.py --kernel /firecracker/build/imgenv/vmlinux-6.1.x\n# SystemExit: No rootfs found and --rootfs was not provided.\n\n# after\npython3 tools/sandbox.py --kernel /firecracker/build/imgenv/vmlinux-6.1.x --rootfs /firecracker/build/imgenv/ubuntu-22.04.ext4","handlingStrategy":"validation","validationCode":"import sys\nfrom framework.artifacts import disks\n\navailable = list(disks(\"*.ext4\"))\nif not available and \"--rootfs\" not in sys.argv[1:]:\n    sys.exit(\"No *.ext4 rootfs found. Download one or pass --rootfs /path/to/rootfs.ext4.\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Fetch an ext4 guest image during dev-environment bootstrap (the amazonlinux-*/ubuntu-* names get default priority).","Convert non-ext4 images (.raw, .qcow2) to .ext4 so discovery picks them up.","Pass --rootfs explicitly in automation rather than depending on the discovered default."],"tags":["python","dev-tooling","firecracker","artifacts","setup"],"backgroundTag":null,"analyzedSha":"ea50487ec11602100b90ed63f85fe00bd30fbde8","analyzedAt":"2026-08-16T11:52:35.093Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}