{"record":{"id":"4e68ecc5f54abf84","repo":"sgl-project/sglang","slug":"metallib-name-not-found-next-to-the-native-meta","errorCode":null,"errorMessage":"{_METALLIB_NAME} not found next to the native Metal extension at {_metallib_path}","messagePattern":"(.+?) not found next to the native Metal extension at (.+?)","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"python/sglang/kernels/aot/python/sgl_kernel/metal.py","lineNumber":18,"sourceCode":"\"\"\"Python entry points for the sgl_kernel Metal extension.\"\"\"\n\nfrom __future__ import annotations\n\nfrom pathlib import Path\nfrom typing import TYPE_CHECKING\n\nif TYPE_CHECKING:\n    import mlx.core as mx\n\n_METALLIB_NAME = \"sgl_metal_kernels.metallib\"\n\ntry:\n    from . import _metal\n\n    _metallib_path = Path(_metal.__file__).resolve().parent / _METALLIB_NAME\n    if not _metallib_path.is_file():\n        raise ImportError(\n            f\"{_METALLIB_NAME} not found next to the native Metal extension \"\n            f\"at {_metallib_path}\"\n        )\n    _metal.register_library(str(_metallib_path))\nexcept ImportError as _exc:  # pragma: no cover - import guarded at call time\n    _metal = None\n    _IMPORT_ERROR: Exception | None = _exc\nelse:\n    _IMPORT_ERROR = None\n\n# Python wrappers for the compiled `_metal.*` entry points go below. Wrappers\n# validate input shapes/dtypes and then invoke AOT C++ entry points. They do\n# not force `mx.eval`, so MLX can keep these calls inside its lazy graph.\n\n\ndef rope_pool_fused(\n    q: mx.array,\n    k: mx.array,","sourceCodeStart":1,"sourceCodeEnd":36,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/kernels/aot/python/sgl_kernel/metal.py#L1-L36","documentation":"This ImportError is raised at import time of sgl_kernel.metal when the default.metallib Metal shader library file is not found next to the compiled native extension (_metal). The Python wrapper verifies the .metallib artifact exists before calling _metal.register_library, because the Metal kernels cannot run without the precompiled shader library. If missing, the module silently sets _metal = None (guarded at call time), so the error surfaces later as a call-time failure on Metal platforms.","triggerScenarios":"Importing sgl_kernel.metal on macOS/Metal builds where the wheel or AOT build did not package default.metallib next to the _metal native extension; broken pip install; building from source without running the Metal AOT kernel build step; manually copying the extension without its .metallib.","commonSituations":"Installing an sgl-kernel wheel built without Metal support; upgrading sgl-kernel to a version with a changed packaging layout; running on non-Apple hardware where Metal artifacts are absent; source builds where CMAKE/BuildMetal step was skipped.","solutions":["Reinstall the wheel: pip install --force-reinstall sgl-kernel (use a macOS/Metal-enabled build)","If building from source, run the Metal AOT build step that produces default.metallib and place it next to the _metal extension .so","Verify the file exists: ls $(python -c \"import sgl_kernel.metal as m; import os; print(os.path.dirname(m.__file__))\")","If on Linux/CUDA, this path is irrelevant — ensure you are not accidentally importing the metal module on a CUDA build"],"exampleFix":"# before: import fails silently, _metal is None\nfrom sgl_kernel import metal\nmetal.rope_pool_fused(...)  # fails at call time\n\n# after: guard at import time\nfrom sgl_kernel import metal\nif metal._metal is None:\n    raise RuntimeError(\"Metal kernels unavailable; reinstall sgl-kernel for macOS\")","handlingStrategy":"try-catch","validationCode":"import importlib.util, pathlib\nspec = importlib.util.find_spec(\"sgl_kernel._metal\")\nmetallib_ok = spec is not None and (pathlib.Path(spec.origin).parent / \"default.metallib\").is_file()","typeGuard":"def metal_available() -> bool:\n    try:\n        from sgl_kernel import metal\n        return metal._metal is not None\n    except Exception:\n        return False","tryCatchPattern":"try:\n    from sgl_kernel import metal\nexcept ImportError:\n    metal = None\nif metal is None or metal._metal is None:\n    raise RuntimeError(\"Metal kernels unavailable; reinstall macOS sgl-kernel build\")","preventionTips":["Install sgl-kernel from an official macOS/Metal wheel matching your version","After install, verify default.metallib sits next to the _metal extension","Guard Metal code paths behind an availability check before first use"],"tags":["metal","macos","installation","import-error","sgl-kernel"],"backgroundTag":"missing-native-library","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}