firecracker-microvm/firecracker · error · SystemExit

{p} not found in container and not under host workspace {hos

Error message

{p} not found in container and not under host workspace {host_root}.

What it means

`translate_host_path` in tools/sandbox.py rewrites host paths into the container-visible /firecracker workspace. When the environment variable HOST_FC_ROOT_DIR is set (i.e. the sandbox runs inside the dev container), a path that is not relative to that host root AND does not exist at its resolved location cannot be mapped, so the script terminates via `raise SystemExit(...)`. This is a path-translation failure between host and container, not a Firecracker failure.

Source

Thrown at tools/sandbox.py:51

        "GB": 2**30,
    }
    match = re.match(r"(?P<val>\d+)(?P<unit>[MG]B)", param.upper())
    return int(match.group("val")) * unit[match.group("unit")]


def translate_host_path(p):
    """Rewrite a host path under HOST_FC_ROOT_DIR to its /firecracker/... equivalent."""
    if p is None:
        return None
    host_root = os.environ.get("HOST_FC_ROOT_DIR")
    if not host_root:
        return Path(p)
    p = Path(p).resolve()
    if p.is_relative_to(host_root):
        return FC_WORKSPACE_DIR / p.relative_to(host_root)
    if p.exists():
        return p
    raise SystemExit(
        f"{p} not found in container and not under host workspace {host_root}."
    )


def pick_default_rootfs(candidates):
    """Default to AL2023, falling back to Ubuntu, then any rootfs available."""
    if not candidates:
        return None
    for prefix in ("amazonlinux-", "ubuntu-"):
        matches = [c for c in candidates if c.name.startswith(prefix)]
        if matches:
            return matches[-1]
    return candidates[-1]


default_rootfs = pick_default_rootfs(rootfs)
default_kernel = kernels[-1] if kernels else None

View on GitHub (pinned to ea50487ec1)

Solutions

1. Copy or move the artifact (kernel, rootfs, cpu template) into the Firecracker workspace on the host so it lands under HOST_FC_ROOT_DIR and maps to /firecracker/... inside the container.
2. Verify the file actually exists at the exact path given (check for typos and for trailing characters); only existing paths are accepted outside the host root.
3. If you are running on the host rather than in the container, unset HOST_FC_ROOT_DIR so translate_host_path returns the path unchanged.
4. If the file lives elsewhere on the host, add it to the container's bind mounts / docker run -v so `p.exists()` succeeds inside the container.

Example fix

# before (artifact outside the shared workspace, not mounted)
HOST_FC_ROOT_DIR=/home/me/firecracker python3 tools/sandbox.py --cpu-template-path /home/me/templates/c3.json
# SystemExit: /home/me/templates/c3.json not found in container and not under host workspace /home/me/firecracker.

# after (artifact inside the workspace, maps to /firecracker/...)
cp /home/me/templates/c3.json /home/me/firecracker/templates/c3.json
python3 tools/sandbox.py --cpu-template-path /firecracker/templates/c3.json

import os
from pathlib import Path

def translatable(p: str) -> bool:
    """True when sandbox.py will accept this path (mirrors translate_host_path)."""
    if p is None:
        return True
    host_root = os.environ.get("HOST_FC_ROOT_DIR")
    if not host_root:
        return True
    q = Path(p).resolve()
    return q.is_relative_to(host_root) or q.exists()

assert translatable(args.cpu_template_path), (
    f"{args.cpu_template_path} is outside {os.environ.get('HOST_FC_ROOT_DIR')} "
    "and does not exist inside the container")

try:
    args.kernel = translate_host_path(args.kernel)
except SystemExit as e:
    print(f"path translation failed: {e}", file=sys.stderr)
    print("put the artifact under the firecracker workspace or bind-mount it", file=sys.stderr)
    raise

When it happens

Trigger: Running `tools/sandbox.py` inside the container with HOST_FC_ROOT_DIR set, while passing `--kernel`, `--rootfs`, `--binary-dir`, or `--cpu-template-path` pointing to a host-only location (e.g. /home/me/vmlinux) that is neither bind-mounted into the container nor present at that resolved path. It also fires for typo'd paths, since only existing paths fall through the `p.exists()` branch.

Common situations: Developer builds in the containerized dev environment but references artifacts downloaded on the host outside the Firecracker checkout; the path exists on the host but was never bind-mounted; a relative path that resolves against a different cwd inside the container; a stale HOST_FC_ROOT_DIR pointing at an old checkout location.

Related errors

• No kernel found and --kernel was not provided.
• No rootfs found and --rootfs was not provided.
• version does not match vX.Y.Z

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