{"record":{"id":"67f01bac90b984cb","repo":"sgl-project/sglang","slug":"hf3fs-fuse-io-is-not-available-please-install-the","errorCode":null,"errorMessage":"hf3fs_fuse.io is not available. Please install the hf3fs_fuse package.","messagePattern":"hf3fs_fuse\\.io is not available\\. Please install the hf3fs_fuse package\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"critical","filePath":"python/sglang/srt/mem_cache/storage/hf3fs/hf3fs_usrbio_client.py","lineNumber":69,"sourceCode":"\n        return wrapper\n\n    return _decorator\n\n\nclass Hf3fsUsrBioClient(Hf3fsClient):\n    \"\"\"HF3FS client implementation using usrbio.\"\"\"\n\n    def __init__(\n        self,\n        path: str,\n        size: int,\n        bytes_per_page: int,\n        entries: int,\n        client_timeout: int,\n    ):\n        if not HF3FS_AVAILABLE:\n            raise ImportError(\n                \"hf3fs_fuse.io is not available. Please install the hf3fs_fuse package.\"\n            )\n\n        self.path = path\n        self.size = size\n        self.bytes_per_page = bytes_per_page\n        self.entries = entries\n        self.client_timeout = client_timeout\n\n        self.file = os.open(self.path, os.O_RDWR | os.O_CREAT)\n        os.ftruncate(self.file, size)\n        register_fd(self.file)\n\n        self.hf3fs_mount_point = extract_mount_point(path)\n        self.bs = self.bytes_per_page\n        self.shm_r = multiprocessing.shared_memory.SharedMemory(\n            size=self.bs * self.entries, create=True\n        )","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/mem_cache/storage/hf3fs/hf3fs_usrbio_client.py#L51-L87","documentation":"HF3FSUsrbIOClient.__init__ raises ImportError when the hf3fs_fuse.io module (flag HF3FS_AVAILABLE) could not be imported at module load. The class is a thin wrapper over that native extension, so construction is impossible without it.","triggerScenarios":"Instantiating HF3FSUsrbIOClient in an environment where pip package hf3fs_fuse (providing fuse.io usrbio bindings) is missing or failed to import (incompatible native build).","commonSituations":"Custom docker image without hf3fs_fuse; installing a wheel built for a different Python/CUDA version so import silently sets HF3FS_AVAILABLE=False; deploying the 3FS storage backend on an unsupported platform.","solutions":["pip install hf3fs_fuse (or the correct wheel matching your Python/glibc/CUDA)","Import sglang.srt.mem_cache.storage.hf3fs.hf3fs_usrio_client manually and inspect the original ImportError to see why the native module failed","Gate the 3FS backend selection on HF3FS_AVAILABLE in your launcher instead of crashing at request time"],"exampleFix":"# before\nclient = HF3FSUsrbIOClient(path, size, bytes_per_page, entries, timeout)\n\n# after\nfrom sglang.srt.mem_cache.storage.hf3fs.hf3fs_usrio_client import HF3FS_AVAILABLE\nassert HF3FS_AVAILABLE, \"install hf3fs_fuse before enabling 3FS hicache\"\nclient = HF3FSUsrbIOClient(path, size, bytes_per_page, entries, timeout)","handlingStrategy":"validation","validationCode":"from sglang.srt.mem_cache.storage.hf3fs.hf3fs_usrio_client import HF3FS_AVAILABLE\n\nif not HF3FS_AVAILABLE:\n    raise SystemExit('hf3fs_fuse not installed; cannot enable 3FS hicache')","typeGuard":"def can_use_usrio() -> bool:\n    try:\n        import hf3fs_fuse.io  # noqa: F401\n        return True\n    except ImportError:\n        return False","tryCatchPattern":"try:\n    from sglang.srt.mem_cache.storage.hf3fs.hf3fs_usrio_client import HF3FSUsrbIOClient\n    client = HF3FSUsrbIOClient(...)\nexcept ImportError as e:\n    logger.warning('3FS unavailable (%s); falling back to local disk hicache', e)\n    client = None","preventionTips":["Bake hf3fs_fuse into the serving docker image and assert the import in CI","Feature-detect HF3FS_AVAILABLE at backend selection time, not at first request"],"tags":["hf3fs","importerror","missing-dependency","installation"],"backgroundTag":"missing-optional-dependency","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}