{"record":{"id":"6df0f5e8489fcc1f","repo":"vllm-project/vllm","slug":"connector-connector-cls-name-does-not-suppor","errorCode":null,"errorMessage":"Connector {connector_cls.__name__} does not support HMA but HMA is enabled. Please set `--disable-hybrid-kv-cache-manager`.","messagePattern":"Connector (.+?) does not support HMA but HMA is enabled\\. Please set `--disable-hybrid-kv-cache-manager`\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/factory.py","lineNumber":57,"sourceCode":"\n        cls._registry[name] = loader\n\n    @classmethod\n    def create_connector(\n        cls,\n        config: \"VllmConfig\",\n        role: KVConnectorRole,\n        kv_cache_config: \"KVCacheConfig\",\n    ) -> KVConnectorBase:\n        kv_transfer_config = config.kv_transfer_config\n        if kv_transfer_config is None:\n            raise ValueError(\"kv_transfer_config must be set to create a connector\")\n        connector_cls = cls.get_connector_class(kv_transfer_config)\n\n        # check if the connector supports HMA\n        hma_enabled = not config.scheduler_config.disable_hybrid_kv_cache_manager\n        if hma_enabled and not cls.supports_hma_config(kv_transfer_config):\n            raise ValueError(\n                f\"Connector {connector_cls.__name__} does not support HMA but \"\n                f\"HMA is enabled. Please set `--disable-hybrid-kv-cache-manager`.\"\n            )\n\n        logger.info(\n            \"Creating v1 connector with name: %s and engine_id: %s\",\n            connector_cls.__name__,\n            kv_transfer_config.engine_id,\n        )\n        # NOTE(Kuntai): v1 connector is explicitly separated into two roles.\n        # Scheduler connector:\n        # - Co-locate with scheduler process\n        # - Should only be used inside the Scheduler class\n        # Worker connector:\n        # - Co-locate with worker process\n        # - Should only be used inside the forward context & attention layer\n        # We build separately to enforce strict separation\n        return connector_cls(config, role, kv_cache_config)","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/factory.py#L39-L75","documentation":"The Hybrid Memory Allocator (HMA) is enabled (default) but the selected KV connector does not declare support for it (checked via supports_hma_config, which resolves the connector class and calls supports_hma). vLLM refuses to mix an HMA-incompatible connector with the hybrid KV cache manager because scheduling assumptions would break.","triggerScenarios":"create_connector runs with scheduler_config.disable_hybrid_kv_cache_manager=False (default) and the connector named in kv_transfer_config does not implement/declare SupportsHMA — e.g. an older or external v1 connector. For MultiConnector, any child lacking HMA support also triggers this.","commonSituations":"Upgrading vLLM where HMA became the default while using a third-party or not-yet-updated connector; combining multiple connectors via MultiConnector where one child lacks HMA support.","solutions":["Add --disable-hybrid-kv-cache-manager to the engine flags (as the message instructs)","Switch to an HMA-supporting connector (one whose class supports HMA)","For custom connectors, implement HMA support so supports_hma() returns True for your class"],"exampleFix":"# before\nllm = LLM(model=..., kv_transfer_config=cfg)\n# HMA enabled by default -> ValueError\n\n# after\nllm = LLM(\n    model=...,\n    kv_transfer_config=cfg,\n    enable_prefix_caching=True,\n)\n# or CLI: vllm serve ... --disable-hybrid-kv-cache-manager","handlingStrategy":"validation","validationCode":"hma_enabled = not vllm_config.scheduler_config.disable_hybrid_kv_cache_manager\nif hma_enabled and not KVConnectorFactory.supports_hma_config(vllm_config.kv_transfer_config):\n    vllm_config.scheduler_config.disable_hybrid_kv_cache_manager = True  # or abort","typeGuard":null,"tryCatchPattern":"try:\n    connector = KVConnectorFactory.create_connector(cfg, role, kv_cache_config)\nexcept ValueError as e:\n    if 'does not support HMA' in str(e):\n        cfg.scheduler_config.disable_hybrid_kv_cache_manager = True\n        connector = KVConnectorFactory.create_connector(cfg, role, kv_cache_config)\n    else:\n        raise","preventionTips":["Pre-flight check supports_hma_config before engine start","Pin connector versions tested with HMA-enabled vLLM","For MultiConnector, verify every child supports HMA, not just the wrapper"],"tags":["kv-transfer","hma","config","vllm"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}