oracle/graal · error · ValueError

Environment variable 'ROOTFS' is unset! It must point to the

Error message

Environment variable 'ROOTFS' is unset! It must point to the CPython file-system root!

What it means

Raised by _resolve_rootfs: GraalHost staged benchmarks need a CPython file-system root (ROOTFS env var) into which the staged benchmark tree and temp dirs are placed (run_stage_run creates a tempdir under rootfs/tmp). If ROOTFS is unset, staging cannot proceed and ValueError is raised.

Source

Thrown at sdk/mx.sdk/mx_sdk_benchmark.py:2251

        self._create_staged_benchmark_run_config_file(build_dir)

    @staticmethod
    def _resolve_graalos_build_dir() -> Path:
        """Verifies that the GRAALOS_BUILD env var is set and points to a directory. Returns the directory path."""
        graalos_build_env_var = os.getenv("GRAALOS_BUILD")
        if graalos_build_env_var is None:
            raise ValueError("Environment variable 'GRAALOS_BUILD' is unset! It must point to the GraalOS build directory!")
        build_dir = Path(graalos_build_env_var).resolve()
        if not build_dir.is_dir():
            raise ValueError(f"Environment variable 'GRAALOS_BUILD' points to '{build_dir}' which is not a directory!")
        return build_dir

    @staticmethod
    def _resolve_rootfs() -> Path:
        """Verifies that the ROOTFS env var is set and points to a directory. Returns the directory path."""
        rootfs_env_var = os.getenv("ROOTFS")
        if rootfs_env_var is None:
            raise ValueError("Environment variable 'ROOTFS' is unset! It must point to the CPython file-system root!")
        rootfs = Path(rootfs_env_var).resolve()
        if not rootfs.is_dir():
            raise ValueError(f"Environment variable 'ROOTFS' points to '{rootfs}' which is not a directory!")
        return rootfs

    @staticmethod
    def _require_executable(path: Path, description: str) -> Path:
        if not path.is_file():
            raise ValueError(f"{description} '{path}' does not exist!")
        if not os.access(path, os.X_OK):
            raise ValueError(f"{description} '{path}' is not executable!")
        return path

    @staticmethod
    def _resolve_graalhost_binary(build_dir: Path) -> Path:
        """Resolve the GraalHost binary from the GraalOS build directory."""
        return GraalHostPolyBenchStagingVm._require_executable(build_dir / "graalhost" / "graalhost", "GraalHost binary")

View on GitHub (pinned to a66e9ccd1d)

Solutions

Export ROOTFS to the prepared CPython root: export ROOTFS=/path/to/cpython-rootfs.
Ensure rootfs/tmp exists and is writable (run_stage_run mkdtemps under it).
Automate both GRAALOS_BUILD and ROOTFS exports in one env script for mx benchmark runs.

Example fix

# before
$ mx benchmark polybench-graalhost   # ValueError: ROOTFS is unset

# after
$ export ROOTFS=$HOME/graalos/cpython-rootfs && mx benchmark polybench-graalhost

Defensive patterns

Strategy: validation

Validate before calling

assert os.environ.get('ROOTFS'), 'export ROOTFS=<cpython rootfs> before running GraalHost benchmarks'

Try / catch

try/except ValueError at entrypoint; report both required vars (GRAALOS_BUILD, ROOTFS) when either is missing.

Prevention

Keep GRAALOS_BUILD and ROOTFS exports together in one setup script.
Ensure rootfs/tmp exists and is writable for the staged tempdir.

When it happens

Trigger: Invoking the image or run stage of a GraalHost PolyBench benchmark without exporting ROOTFS; commonly the second of the two required env vars (with GRAALOS_BUILD) that gets forgotten.

Common situations: Partial environment setup in CI; docs that only mention GRAALOS_BUILD; running on a machine where the CPython rootfs was prepared once but never exported in the current shell.

Related errors

AI-assisted analysis of oracle/graal@a66e9ccd1d (2026-08-14). Data as JSON: /api/errors/b6c87c2810444af5. Report an issue: GitHub.