{"record":{"id":"ab7ddb723065371f","repo":"vllm-project/vllm","slug":"mooncake-preferred-segment-override-must-be-a-non","errorCode":null,"errorMessage":"Mooncake preferred_segment override must be a non-empty string","messagePattern":"Mooncake preferred_segment override must be a non-empty string","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/mooncake/rdma_utils.py","lineNumber":35,"sourceCode":"    normalized = value.strip()\n    return normalized or None\n\n\ndef get_requester_local_hostname(local_ip: str) -> str:\n    override = normalize_string_override(envs.MOONCAKE_REQUESTER_LOCAL_HOSTNAME)\n    if override is not None:\n        return override\n    return local_ip\n\n\ndef get_configured_preferred_segment(\n    extra_config: Mapping[str, Any],\n) -> str | None:\n    preferred_segment = normalize_string_override(extra_config.get(\"preferred_segment\"))\n    if preferred_segment is not None:\n        return preferred_segment\n    if extra_config.get(\"preferred_segment\") is not None:\n        raise ValueError(\n            \"Mooncake preferred_segment override must be a non-empty string\"\n        )\n\n    env_value = normalize_string_override(envs.MOONCAKE_PREFERRED_SEGMENT)\n    if env_value is not None:\n        logger.info(\n            \"Mooncake preferred_segment from MOONCAKE_PREFERRED_SEGMENT: %s\",\n            env_value,\n        )\n        return env_value\n    return None\n","sourceCodeStart":17,"sourceCodeEnd":47,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/mooncake/rdma_utils.py#L17-L47","documentation":"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.","triggerScenarios":"Setting kv_connector_extra_config={'preferred_segment': ''} (or '   ', None, 123) in the KV transfer config while using MooncakeTransferEngine/RDMA.","commonSituations":"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.","solutions":["Remove the 'preferred_segment' key from kv_connector_extra_config entirely so the env var / auto-detection path is used","Or set it to a real non-empty RDMA segment name, e.g. 'preferred_segment': 'rocep5s0'","If the value should come from the environment, delete the extra_config key and export MOONCAKE_PREFERRED_SEGMENT instead"],"exampleFix":"# before\nkv_transfer_config = KVTransferConfig(\n    kv_connector_extra_config={\"preferred_segment\": \"\"},  # -> ValueError\n)\n\n# after\nkv_transfer_config = KVTransferConfig(\n    kv_connector_extra_config={\"preferred_segment\": \"rocep5s0\"},\n)","handlingStrategy":"type-guard","validationCode":"seg = extra_config.get(\"preferred_segment\")\nif seg is not None and (not isinstance(seg, str) or not seg.strip()):\n    raise ValueError(\"preferred_segment must be a non-empty string\")","typeGuard":"def is_valid_preferred_segment(v) -> bool:\n    return v is None or (isinstance(v, str) and len(v.strip()) > 0)","tryCatchPattern":null,"preventionTips":["Omit optional keys rather than setting them to empty strings","Validate kv_connector_extra_config against a schema before starting vLLM","Prefer the MOONCAKE_PREFERRED_SEGMENT env var for environment-specific overrides"],"tags":["mooncake","rdma","config","validation"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}