vllm-project/vllm · error · ValueError

kv_connector_module_path cannot be an empty string.

Error message

kv_connector_module_path cannot be an empty string.

What it means

kv_connector_module_path was set to an empty string, which the factory treats as an invalid value (None means 'use registry', a non-empty string means 'import this module'). An empty string is almost always a serialization/template artifact rather than an intentional choice, so it is rejected explicitly.

Source

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

            connector_name: Name of the registered connector.

        Returns:
            The connector class.
        """
        if connector_name not in cls._registry:
            raise ValueError(f"Connector '{connector_name}' is not registered.")
        return cls._registry[connector_name]()

    @classmethod
    def get_connector_class(
        cls, kv_transfer_config: "KVTransferConfig"
    ) -> type[KVConnectorBaseType]:
        connector_name = kv_transfer_config.kv_connector
        if connector_name is None:
            raise ValueError("Connector name is not set in KVTransferConfig")
        connector_module_path = kv_transfer_config.kv_connector_module_path
        if connector_module_path is not None and not connector_module_path:
            raise ValueError("kv_connector_module_path cannot be an empty string.")
        if connector_module_path:
            # External module path takes priority over internal registry.
            connector_module = importlib.import_module(connector_module_path)
            try:
                connector_cls = getattr(connector_module, connector_name)
            except AttributeError as e:
                raise AttributeError(
                    f"Class {connector_name} not found in {connector_module_path}"
                ) from e
            connector_cls = cast(type[KVConnectorBaseType], connector_cls)
            if not supports_kw(connector_cls, "kv_cache_config"):
                msg = (
                    f"Connector {connector_cls.__name__} uses deprecated "
                    "2-argument constructor signature. External v1 KV "
                    "connectors must accept kv_cache_config as the third "
                    "constructor argument and pass it to super().__init__()."
                )
                logger.error(msg)

View on GitHub (pinned to c794754062)

Solutions

1. Remove the kv_connector_module_path key (or set it to null) when using a built-in connector
2. Set it to the real importable module path when using an external connector, e.g. "my_pkg.connectors"

Example fix

# before
{"kv_connector": "NixlConnector", "kv_connector_module_path": ""}

# after
{"kv_connector": "NixlConnector"}
# or
{"kv_connector": "MyConnector", "kv_connector_module_path": "my_pkg.connectors"}

path = kv_transfer_config.kv_connector_module_path
if path is not None and not path:
    kv_transfer_config.kv_connector_module_path = None  # normalize empty to None

When it happens

Trigger: Passing kv_connector_module_path="" in --kv-transfer-config JSON or in a programmatically built KVTransferConfig; often from templated configs where the field is filled conditionally.

Common situations: Helm/YAML templates that render an empty module path; env-var-driven configs that expand to empty; copying an example config and blanking the field instead of deleting it.

Related errors

• HTTP request failed: {0}
• 'mm_shm_cache_max_object_size_mb' should only be set when 'm
• 'mm_encoder_fp8_scale_path' and 'mm_encoder_fp8_scale_save_p
• 'mm_encoder_fp8_scale_save_path' cannot be used with 'mm_enc
• Invalid "device" in mm_processor_kwargs: {device!r}. Expecte

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