{"record":{"id":"b88db078d7f43906","repo":"vllm-project/vllm","slug":"flexkv-is-not-installed-please-install-it-to-use","errorCode":null,"errorMessage":"FlexKV is not installed. Please install it to use FlexKVConnectorV1. See https://github.com/taco-project/FlexKV for installation instructions.","messagePattern":"FlexKV is not installed\\. Please install it to use FlexKVConnectorV1\\. See https://github\\.com/taco-project/FlexKV for installation instructions\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/flexkv_connector.py","lineNumber":68,"sourceCode":"        Pass ``kv_connector=\"FlexKVConnectorV1\"`` via ``--kv-transfer-config``::\n\n            --kv-transfer-config \\\n            '{\"kv_connector\":\"FlexKVConnectorV1\",\"kv_role\":\"kv_both\"}'\n    \"\"\"\n\n    def __init__(\n        self,\n        vllm_config: \"VllmConfig\",\n        role: KVConnectorRole,\n        kv_cache_config: \"KVCacheConfig\",\n    ):\n        super().__init__(\n            vllm_config=vllm_config, role=role, kv_cache_config=kv_cache_config\n        )\n        try:\n            from flexkv.integration.vllm.vllm_v1_adapter import FlexKVConnectorV1Impl\n        except ImportError as e:\n            raise ImportError(\n                \"FlexKV is not installed. Please install it to use \"\n                \"FlexKVConnectorV1. See https://github.com/taco-project/FlexKV \"\n                \"for installation instructions.\"\n            ) from e\n\n        self._flexkv_connector = FlexKVConnectorV1Impl(vllm_config, role)\n\n    def shutdown(self):\n        self._flexkv_connector.shutdown()\n\n    # ==============================\n    # Worker-side methods\n    # ==============================\n    def start_load_kv(self, forward_context: \"ForwardContext\", **kwargs) -> None:\n        \"\"\"No-op for FlexKV (currently).\n\n        FlexKV manages all KV transfers on the **scheduler side** via\n        ``build_connector_meta`` (which calls ``launch_tasks``) and","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/flexkv_connector.py#L50-L86","documentation":"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.","triggerScenarios":"Selecting kv_connector='FlexKVConnectorV1' without the FlexKV package installed in the vLLM Python environment.","commonSituations":"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.","solutions":["Install FlexKV per https://github.com/taco-project/FlexKV into the same environment as vLLM","Verify with: python -c \"from flexkv.integration.vllm.vllm_v1_adapter import FlexKVConnectorV1Impl\"","If the import still fails, check FlexKV's own dependencies (its ImportError chain is preserved as __cause__)"],"exampleFix":"# before\npip install vllm  # FlexKV missing -> ImportError at connector init\n\n# after\npip install vllm\npip install flexkv  # or follow taco-project/FlexKV install instructions","handlingStrategy":"try-catch","validationCode":"try:\n    from flexkv.integration.vllm.vllm_v1_adapter import FlexKVConnectorV1Impl  # noqa\nexcept ImportError:\n    raise SystemExit(\"Install FlexKV before selecting FlexKVConnectorV1\")","typeGuard":null,"tryCatchPattern":"try:\n    connector = FlexKVConnectorV1(cfg, role, kv_cache_config)\nexcept ImportError as e:\n    raise SystemExit(f\"Missing dependency: {e}\") from e","preventionTips":["Pre-install optional connector dependencies in the serving image","Add dependency smoke tests to deployment pipelines"],"tags":["kv-transfer","import","flexkv","dependencies","vllm"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}