vllm-project/vllm · error · ValueError

Mooncake preferred_segment override must be a non-empty stri

Error message

Mooncake preferred_segment override must be a non-empty string

What it means

Thrown while resolving the Mooncake RDMA preferred segment: kv_connector_extra_config contains a 'preferred_segment' key, but normalize_string_override returned None for it — meaning the value is not a non-empty string (e.g. empty string, whitespace-only, or a non-string like an int/null that fails normalization). The code explicitly distinguishes 'key present but unusable' from 'key absent', and only the latter falls through to the MOONCAKE_PREFERRED_SEGMENT env var.

Source

Thrown at vllm/distributed/kv_transfer/kv_connector/v1/mooncake/rdma_utils.py:35

    normalized = value.strip()
    return normalized or None


def get_requester_local_hostname(local_ip: str) -> str:
    override = normalize_string_override(envs.MOONCAKE_REQUESTER_LOCAL_HOSTNAME)
    if override is not None:
        return override
    return local_ip


def get_configured_preferred_segment(
    extra_config: Mapping[str, Any],
) -> str | None:
    preferred_segment = normalize_string_override(extra_config.get("preferred_segment"))
    if preferred_segment is not None:
        return preferred_segment
    if extra_config.get("preferred_segment") is not None:
        raise ValueError(
            "Mooncake preferred_segment override must be a non-empty string"
        )

    env_value = normalize_string_override(envs.MOONCAKE_PREFERRED_SEGMENT)
    if env_value is not None:
        logger.info(
            "Mooncake preferred_segment from MOONCAKE_PREFERRED_SEGMENT: %s",
            env_value,
        )
        return env_value
    return None

View on GitHub (pinned to c794754062)

Solutions

1. Remove the 'preferred_segment' key from kv_connector_extra_config entirely so the env var / auto-detection path is used
2. Or set it to a real non-empty RDMA segment name, e.g. 'preferred_segment': 'rocep5s0'
3. If the value should come from the environment, delete the extra_config key and export MOONCAKE_PREFERRED_SEGMENT instead

Example fix

# before
kv_transfer_config = KVTransferConfig(
    kv_connector_extra_config={"preferred_segment": ""},  # -> ValueError
)

# after
kv_transfer_config = KVTransferConfig(
    kv_connector_extra_config={"preferred_segment": "rocep5s0"},
)

seg = extra_config.get("preferred_segment")
if seg is not None and (not isinstance(seg, str) or not seg.strip()):
    raise ValueError("preferred_segment must be a non-empty string")

def is_valid_preferred_segment(v) -> bool:
    return v is None or (isinstance(v, str) and len(v.strip()) > 0)

When it happens

Trigger: Setting kv_connector_extra_config={'preferred_segment': ''} (or ' ', None, 123) in the KV transfer config while using MooncakeTransferEngine/RDMA.

Common situations: Template/helm values that render an empty string for an optional field; users trying to 'unset' the option by giving it an empty value instead of removing the key; YAML anchors leaving the key present with a blank value.

Related errors

• embedded mode requires global_segment_size > 0
• Mooncake Transfer Engine initialization failed.
• unknown Mooncake mode: {self.mode!r}
• local_buffer_size must be > 0
• standalone-store mode requires global_segment_size == 0

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