vllm-project/vllm · error · 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

Hf3fsClient.__init__ checks the module-level HF3FS_AVAILABLE flag (set by a try-import of hf3fs_fuse.io) and raises ImportError when the hf3fs_fuse package is absent. The HF3FS connector stores KV pages in a shared file via hf3fs_fuse, so the package is a hard requirement.

Source

Thrown at vllm/distributed/kv_transfer/kv_connector/v1/hf3fs/hf3fs_client.py:72

                return func(self, *args, **kwargs)

        return wrapper

    return _decorator


class Hf3fsClient:
    def __init__(self, path: str, size: int, bytes_per_page: int, entries: int):
        """Initialize the HF3FS client with hf3fs_fuse.

        Args:
            path: Path to the file used for storage
            size: Total size of the storage file in bytes
            bytes_per_page: Size of each page in bytes
            entries: Maximum number of concurrent operations
        """
        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._closed = False

        self.file = None
        self.shm_r = None
        self.shm_w = None
        self.ior_r = None
        self.ior_w = None
        self.iov_r = None
        self.iov_w = None
        try:

View on GitHub (pinned to c794754062)

Solutions

1. Install the hf3fs_fuse package into the vLLM environment (pip install hf3fs-fuse or per project docs)
2. Verify: python -c "import hf3fs_fuse.io"
3. If using containers, rebuild the image with hf3fs_fuse included

Example fix

# before
client = Hf3fsClient(path, size, bytes_per_page, entries)  # hf3fs_fuse missing

# after
pip install hf3fs_fuse
client = Hf3fsClient(path, size, bytes_per_page, entries)

try:
    import hf3fs_fuse.io  # noqa
except ImportError:
    raise SystemExit("Install hf3fs_fuse before using the HF3FS connector")

try:
    client = Hf3fsClient(path, size, bytes_per_page, entries)
except ImportError as e:
    raise SystemExit(f"Missing dependency: {e}") from e

When it happens

Trigger: Instantiating Hf3fsClient (directly or via the HF3FS KV connector) in a Python environment where 'import hf3fs_fuse.io' failed at module load time.

Common situations: Using the SharedStorage/HF3FS connector without installing hf3fs_fuse; running in a container image that lacks the package; hf3fs_fuse installed for a different Python interpreter.

Related errors

• FlexKV is not installed. Please install it to use FlexKVConn
• Class {connector_name} not found in {connector_module_path}
• Hf3fsClient.check Failed
• Rank {rank} not initialized
• Invalid initialization parameters

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/bcce4996a1e67ada. Report an issue: GitHub.