sgl-project/sglang · error · RuntimeError

metal_shader_sources is empty; nothing to compile

Error message

metal_shader_sources is empty; nothing to compile

What it means

The Metal build step requires a non-empty list of .metal shader sources to compile. If metal_shader_sources resolves empty (nothing matched, or the extension was declared without shader files), it raises rather than producing an extension with no GPU code.

Source

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

        metallib_path = generated_dir / metallib_name
        metal_std = os.environ.get("SGL_METAL_STD", "metal3.1")

        ext_include_dirs = [Path(p) for p in (ext.include_dirs or [])]
        host_includes = [
            python_include,
            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),

View on GitHub (pinned to 0132848349)

Solutions

1. Check the glob/source list used to build metal_shader_sources and verify the .metal files exist in the checkout
2. Run the build from the repository root (paths are resolved relative to the setup script)
3. Fix or remove the extension declaration if no shaders are intended

Example fix

# before
metal_shader_sources = sorted(glob('csrc/metal/*.metall'))
# after
metal_shader_sources = sorted(glob('csrc/metal/*.metal'))
assert metal_shader_sources, 'no metal shaders found'

assert metal_shader_sources, 'no .metal files matched'

When it happens

Trigger: Declaring a BuildMetalExtension-backed Extension whose sources include no .metal files, or glob patterns (e.g. csrc/**/*.metal) that match nothing because the checkout/layout changed.

Common situations: Repo restructures moving shader directories; typos in glob patterns; building a source tarball that excluded .metal files.

Related errors

• metal shader source not found: {metal_src}
• 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/252117a95e8f2d76. Report an issue: GitHub.