sgl-project/sglang · error · RuntimeError

metal shader source not found: {metal_src}

Error message

metal shader source not found: {metal_src}

What it means

Each entry in metal_shader_sources is resolved to a file under the project root and must exist before `xcrun metal` compiles it. A listed-but-missing .metal file raises with the offending path.

Source

Thrown at python/sglang/kernels/aot/setup_metal.py:184

            nanobind_dir / "include",
            nanobind_dir / "ext" / "robin_map" / "include",
            mlx_include,
            mlx_include / "metal_cpp",
        ]
        all_includes = ext_include_dirs + host_includes
        include_args = [f"-I{p}" for p in all_includes]
        # `xcrun metal` accepts `-I` for header search; reuse the project
        # include dirs so shaders can include shared MSL headers.
        metal_include_args = [f"-I{p}" for p in ext_include_dirs]

        if not metal_shader_sources:
            raise RuntimeError("metal_shader_sources is empty; nothing to compile")

        air_paths = []
        for rel in metal_shader_sources:
            metal_src = root / rel
            if not metal_src.is_file():
                raise RuntimeError(f"metal shader source not found: {metal_src}")
            air_path = generated_dir / (metal_src.stem + ".air")
            self.spawn(
                [
                    "xcrun",
                    "-sdk",
                    "macosx",
                    "metal",
                    f"-std={metal_std}",
                    *metal_flags,
                    *metal_include_args,
                    "-c",
                    str(metal_src),
                    "-o",
                    str(air_path),
                ]
            )
            air_paths.append(str(air_path))

View on GitHub (pinned to 0132848349)

Solutions

1. Verify the printed path exists; update the source list/glob to the new filename or directory
2. Build from the repo root so Path(__file__).parent-relative resolution matches
3. Clean cached build state (build/ dir) after shader renames

Example fix

# before
metal_shader_sources = ['csrc/metal/rope_old.metal']
# after
metal_shader_sources = ['csrc/metal/rope.metal']  # matches current file

assert all((root/rel).is_file() for rel in metal_shader_sources)

When it happens

Trigger: metal_shader_sources references a renamed/moved/deleted .metal file (stale list, hardcoded names, or glob evaluated from the wrong root), so metal_src.is_file() is False.

Common situations: Shader renames in a newer commit while a cached/hardcoded source list is reused; building from a subdirectory so root-relative paths miss; sparse checkouts missing files.

Related errors

• metal_shader_sources is empty; nothing to compile
• setup_metal.py only supports macOS (Apple Silicon).
• Apple toolchain not found. Install the Xcode Command Line To
• Apple Metal shader compiler not found. Install a full Xcode
• {_METALLIB_NAME} not found next to the native Metal extensio

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/3a54607f94de109f. Report an issue: GitHub.