{"record":{"id":"b90bc31c78a4c9e6","repo":"firecracker-microvm/firecracker","slug":"no-kernel-found-and-kernel-was-not-provided","errorCode":null,"errorMessage":"No kernel found and --kernel was not provided.","messagePattern":"No kernel found and --kernel was not provided\\.","errorType":"exception","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"tools/sandbox.py","lineNumber":111,"sourceCode":"parser.add_argument(\"--cpu-template-path\", help=\"CPU template to use\", type=Path)\nparser.add_argument(\n    \"--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)","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/firecracker-microvm/firecracker/blob/ea50487ec11602100b90ed63f85fe00bd30fbde8/tools/sandbox.py#L93-L129","documentation":"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.","triggerScenarios":"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.","commonSituations":"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-*`.","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."],"exampleFix":"# before\npython3 tools/sandbox.py\n# SystemExit: No kernel found and --kernel was not provided.\n\n# after\npython3 tools/sandbox.py --kernel /firecracker/build/imgenv/vmlinux-6.1.x","handlingStrategy":"validation","validationCode":"import sys\nfrom pathlib import Path\nfrom framework.artifacts import kernels\n\navailable = list(kernels(\"vmlinux-*\"))\nif not available and \"--kernel\" not in sys.argv[1:]:\n    sys.exit(\"No vmlinux-* kernel found in the artifact directories. \"\n             \"Download one or pass --kernel /path/to/vmlinux.\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"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"}