sgl-project/sglang · critical · ImportError

hf3fs_fuse.io is not available. Please install the hf3fs_fus

Error message

hf3fs_fuse.io is not available. Please install the hf3fs_fuse package.

What it means

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.

Source

Thrown at python/sglang/srt/mem_cache/storage/hf3fs/hf3fs_usrbio_client.py:69

        return wrapper

    return _decorator


class Hf3fsUsrBioClient(Hf3fsClient):
    """HF3FS client implementation using usrbio."""

    def __init__(
        self,
        path: str,
        size: int,
        bytes_per_page: int,
        entries: int,
        client_timeout: int,
    ):
        if not HF3FS_AVAILABLE:
            raise ImportError(
                "hf3fs_fuse.io is not available. Please install the hf3fs_fuse package."
            )

        self.path = path
        self.size = size
        self.bytes_per_page = bytes_per_page
        self.entries = entries
        self.client_timeout = client_timeout

        self.file = os.open(self.path, os.O_RDWR | os.O_CREAT)
        os.ftruncate(self.file, size)
        register_fd(self.file)

        self.hf3fs_mount_point = extract_mount_point(path)
        self.bs = self.bytes_per_page
        self.shm_r = multiprocessing.shared_memory.SharedMemory(
            size=self.bs * self.entries, create=True
        )

View on GitHub (pinned to 0132848349)

Solutions

1. pip install hf3fs_fuse (or the correct wheel matching your Python/glibc/CUDA)
2. Import sglang.srt.mem_cache.storage.hf3fs.hf3fs_usrio_client manually and inspect the original ImportError to see why the native module failed
3. Gate the 3FS backend selection on HF3FS_AVAILABLE in your launcher instead of crashing at request time

Example fix

# before
client = HF3FSUsrbIOClient(path, size, bytes_per_page, entries, timeout)

# after
from sglang.srt.mem_cache.storage.hf3fs.hf3fs_usrio_client import HF3FS_AVAILABLE
assert HF3FS_AVAILABLE, "install hf3fs_fuse before enabling 3FS hicache"
client = HF3FSUsrbIOClient(path, size, bytes_per_page, entries, timeout)

from sglang.srt.mem_cache.storage.hf3fs.hf3fs_usrio_client import HF3FS_AVAILABLE

if not HF3FS_AVAILABLE:
    raise SystemExit('hf3fs_fuse not installed; cannot enable 3FS hicache')

def can_use_usrio() -> bool:
    try:
        import hf3fs_fuse.io  # noqa: F401
        return True
    except ImportError:
        return False

try:
    from sglang.srt.mem_cache.storage.hf3fs.hf3fs_usrio_client import HF3FSUsrbIOClient
    client = HF3FSUsrbIOClient(...)
except ImportError as e:
    logger.warning('3FS unavailable (%s); falling back to local disk hicache', e)
    client = None

When it happens

Trigger: Instantiating HF3FSUsrbIOClient in an environment where pip package hf3fs_fuse (providing fuse.io usrbio bindings) is missing or failed to import (incompatible native build).

Common situations: 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.

Related errors

• LMCache is not installed. Please install it by running `pip
• Sparse Video Gen 2 attention backend requires svg package to
• Humming quantization requires `humming-kernels`. Please inst
• Please install mooncake by following the instructions at htt
• The fastokens package is required when --tokenizer-backend=f

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