vllm-project/vllm · error · ImportError

FlexKV is not installed. Please install it to use FlexKVConn

Error message

FlexKV is not installed. Please install it to use FlexKVConnectorV1. See https://github.com/taco-project/FlexKV for installation instructions.

What it means

FlexKVConnectorV1 lazily imports the FlexKV vLLM adapter (flexkv.integration.vllm.vllm_v1_adapter.FlexKVConnectorV1Impl) in __init__; if the import fails, it re-raises an ImportError pointing at the FlexKV project. The connector class in vLLM is a thin wrapper — the actual implementation ships in the separate FlexKV package.

Source

Thrown at vllm/distributed/kv_transfer/kv_connector/v1/flexkv_connector.py:68

        Pass ``kv_connector="FlexKVConnectorV1"`` via ``--kv-transfer-config``::

            --kv-transfer-config \
            '{"kv_connector":"FlexKVConnectorV1","kv_role":"kv_both"}'
    """

    def __init__(
        self,
        vllm_config: "VllmConfig",
        role: KVConnectorRole,
        kv_cache_config: "KVCacheConfig",
    ):
        super().__init__(
            vllm_config=vllm_config, role=role, kv_cache_config=kv_cache_config
        )
        try:
            from flexkv.integration.vllm.vllm_v1_adapter import FlexKVConnectorV1Impl
        except ImportError as e:
            raise ImportError(
                "FlexKV is not installed. Please install it to use "
                "FlexKVConnectorV1. See https://github.com/taco-project/FlexKV "
                "for installation instructions."
            ) from e

        self._flexkv_connector = FlexKVConnectorV1Impl(vllm_config, role)

    def shutdown(self):
        self._flexkv_connector.shutdown()

    # ==============================
    # Worker-side methods
    # ==============================
    def start_load_kv(self, forward_context: "ForwardContext", **kwargs) -> None:
        """No-op for FlexKV (currently).

        FlexKV manages all KV transfers on the **scheduler side** via
        ``build_connector_meta`` (which calls ``launch_tasks``) and

View on GitHub (pinned to c794754062)

Solutions

1. Install FlexKV per https://github.com/taco-project/FlexKV into the same environment as vLLM
2. Verify with: python -c "from flexkv.integration.vllm.vllm_v1_adapter import FlexKVConnectorV1Impl"
3. If the import still fails, check FlexKV's own dependencies (its ImportError chain is preserved as __cause__)

Example fix

# before
pip install vllm  # FlexKV missing -> ImportError at connector init

# after
pip install vllm
pip install flexkv  # or follow taco-project/FlexKV install instructions

try:
    from flexkv.integration.vllm.vllm_v1_adapter import FlexKVConnectorV1Impl  # noqa
except ImportError:
    raise SystemExit("Install FlexKV before selecting FlexKVConnectorV1")

try:
    connector = FlexKVConnectorV1(cfg, role, kv_cache_config)
except ImportError as e:
    raise SystemExit(f"Missing dependency: {e}") from e

When it happens

Trigger: Selecting kv_connector='FlexKVConnectorV1' without the FlexKV package installed in the vLLM Python environment.

Common situations: Fresh deployment forgetting the extra dependency; installing FlexKV into a different venv/conda env than the one running vLLM; FlexKV installed but its own transitive dependencies missing so the import chain fails.

Related errors

• hf3fs_fuse.io is not available. Please install the hf3fs_fus
• Class {connector_name} not found in {connector_module_path}
• HTTP request failed: {0}
• JSON error: {0}
• Tokenizer error: {0}

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