vllm-project/vllm · error · ValueError

Connector {connector_cls.__name__} does not support HMA but

Error message

Connector {connector_cls.__name__} does not support HMA but HMA is enabled. Please set `--disable-hybrid-kv-cache-manager`.

What it means

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.

Source

Thrown at vllm/distributed/kv_transfer/kv_connector/factory.py:57

        cls._registry[name] = loader

    @classmethod
    def create_connector(
        cls,
        config: "VllmConfig",
        role: KVConnectorRole,
        kv_cache_config: "KVCacheConfig",
    ) -> KVConnectorBase:
        kv_transfer_config = config.kv_transfer_config
        if kv_transfer_config is None:
            raise ValueError("kv_transfer_config must be set to create a connector")
        connector_cls = cls.get_connector_class(kv_transfer_config)

        # check if the connector supports HMA
        hma_enabled = not config.scheduler_config.disable_hybrid_kv_cache_manager
        if hma_enabled and not cls.supports_hma_config(kv_transfer_config):
            raise ValueError(
                f"Connector {connector_cls.__name__} does not support HMA but "
                f"HMA is enabled. Please set `--disable-hybrid-kv-cache-manager`."
            )

        logger.info(
            "Creating v1 connector with name: %s and engine_id: %s",
            connector_cls.__name__,
            kv_transfer_config.engine_id,
        )
        # NOTE(Kuntai): v1 connector is explicitly separated into two roles.
        # Scheduler connector:
        # - Co-locate with scheduler process
        # - Should only be used inside the Scheduler class
        # Worker connector:
        # - Co-locate with worker process
        # - Should only be used inside the forward context & attention layer
        # We build separately to enforce strict separation
        return connector_cls(config, role, kv_cache_config)

View on GitHub (pinned to c794754062)

Solutions

  1. Add --disable-hybrid-kv-cache-manager to the engine flags (as the message instructs)
  2. Switch to an HMA-supporting connector (one whose class supports HMA)
  3. For custom connectors, implement HMA support so supports_hma() returns True for your class

Example fix

# before
llm = LLM(model=..., kv_transfer_config=cfg)
# HMA enabled by default -> ValueError

# after
llm = LLM(
    model=...,
    kv_transfer_config=cfg,
    enable_prefix_caching=True,
)
# or CLI: vllm serve ... --disable-hybrid-kv-cache-manager
Defensive patterns

Strategy: validation

Validate before calling

hma_enabled = not vllm_config.scheduler_config.disable_hybrid_kv_cache_manager
if hma_enabled and not KVConnectorFactory.supports_hma_config(vllm_config.kv_transfer_config):
    vllm_config.scheduler_config.disable_hybrid_kv_cache_manager = True  # or abort

Try / catch

try:
    connector = KVConnectorFactory.create_connector(cfg, role, kv_cache_config)
except ValueError as e:
    if 'does not support HMA' in str(e):
        cfg.scheduler_config.disable_hybrid_kv_cache_manager = True
        connector = KVConnectorFactory.create_connector(cfg, role, kv_cache_config)
    else:
        raise

Prevention

When it happens

Trigger: 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.

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

Related errors

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