oracle/graal · error · ValueError

Environment variable 'GRAALOS_BUILD' is unset! It must point

Error message

Environment variable 'GRAALOS_BUILD' is unset! It must point to the GraalOS build directory!

What it means

Raised by GraalHostPolyBenchStagingVm._resolve_graalos_build_dir: the GRAALOS_BUILD environment variable must be set for GraalHost staged benchmarks because the run stage needs the GraalOS build artifacts (graalhost binary, config files). Unset means the environment was not provisioned, and a ValueError is thrown before staging starts.

Source

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

        super()._prepare_for_running(args, out, err, cwd, nonZeroIsFatal)
        benchmark: str = bm_exec_context().get("benchmark")
        if benchmark.startswith("interpreter/c-"):
            # Disable C-native-extension benchmarks on GraalOS due to os.symlink not being supported (GR-71952)
            mx.abort(f"Benchmark '{benchmark}' (and all other C-native-extension benchmarks) is not supported on GraalHost!")

    def run_stage_image(self):
        # Start with resolving prerequisite environment variables
        build_dir = self._resolve_graalos_build_dir()
        # Stage benchmark
        super().run_stage_image()
        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:

View on GitHub (pinned to a66e9ccd1d)

Solutions

  1. Export GRAALOS_BUILD to the GraalOS build directory: export GRAALOS_BUILD=/path/to/graalos/build.
  2. Add the export to the CI environment or the suite's env-setup script so all mx benchmark invocations inherit it.
  3. Confirm the directory actually contains graalhost/graalhost to avoid the follow-up executable errors.

Example fix

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

# after
$ export GRAALOS_BUILD=$HOME/graalos/build && mx benchmark polybench-graalhost
Defensive patterns

Strategy: validation

Validate before calling

import os
assert os.environ.get('GRAALOS_BUILD'), 'export GRAALOS_BUILD=<graalos build dir> before running GraalHost benchmarks'

Try / catch

try/except ValueError at the benchmark entrypoint; convert to a friendly message telling the user which env var to export.

Prevention

When it happens

Trigger: Running a GraalHost PolyBench benchmark (run_stage_image or run_stage_run) without exporting GRAALOS_BUILD, e.g. 'mx benchmark polybench-graalhost ...' in a shell that never sourced the GraalOS build environment.

Common situations: CI jobs or fresh shells that skip the GraalOS setup step; developers running only part of the staged pipeline assuming defaults exist.

Related errors

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