vllm-project/vllm · error · ValueError

unknown Mooncake mode: {self.mode!r}

Error message

unknown Mooncake mode: {self.mode!r}

What it means

MooncakeStoreConfig.__post_init__ validates the parsed mooncake store config file; 'mode' must be exactly 'embedded' or 'standalone-store'. Anything else (typo, different casing, missing quotes in JSON producing a bad value) is rejected at construction time before any mooncake API is touched.

Source

Thrown at vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/worker.py:142

    ``mode`` selects the topology: ``embedded`` (each rank contributes
    ``global_segment_size`` in-process) or ``standalone-store`` (rank
    contributes 0; an external ``mooncake_client`` process owns the pool
    and the SSD tier).
    """

    metadata_server: str
    master_server_address: str
    protocol: str
    device_name: str
    mode: MooncakeMode = "embedded"
    global_segment_size: int = DEFAULT_GLOBAL_SEGMENT_SIZE
    local_buffer_size: int = DEFAULT_LOCAL_BUFFER_SIZE
    enable_offload: bool = False
    tenant_id: str = DEFAULT_TENANT_ID

    def __post_init__(self) -> None:
        if self.mode not in ("embedded", "standalone-store"):
            raise ValueError(f"unknown Mooncake mode: {self.mode!r}")
        if self.local_buffer_size <= 0:
            raise ValueError("local_buffer_size must be > 0")
        if self.mode == "embedded" and self.global_segment_size == 0:
            raise ValueError("embedded mode requires global_segment_size > 0")
        if self.mode == "standalone-store" and self.global_segment_size != 0:
            raise ValueError("standalone-store mode requires global_segment_size == 0")

    @staticmethod
    def from_file(file_path: str) -> "MooncakeStoreConfig":
        with open(file_path) as file:
            config = json.load(file)
        return MooncakeStoreConfig(
            metadata_server=config.get("metadata_server", ""),
            master_server_address=config.get("master_server_address", ""),
            protocol=config.get("protocol", "rdma"),
            device_name=config.get("device_name", ""),
            mode=config.get("mode", "embedded"),
            global_segment_size=_parse_size(

View on GitHub (pinned to c794754062)

Solutions

1. Set "mode": "embedded" (store runs inside the vLLM process with a transfer-engine segment) or "mode": "standalone-store" (talk to an external mooncake store service)
2. Check the JSON spelling in the file pointed to by MOONCAKE_CONFIG_PATH

Example fix

// before (mooncake.json)
{ "mode": "standalone" }

// after
{ "mode": "standalone-store" }

raw = json.load(open(path))
if raw.get("mode") not in ("embedded", "standalone-store"):
    raise ValueError(f"bad mode {raw.get('mode')!r}; use embedded or standalone-store")

def is_valid_mooncake_mode(v) -> bool:
    return isinstance(v, str) and v in ("embedded", "standalone-store")

When it happens

Trigger: Writing "mode": "standalone" or "embedding" or leaving a stale value in the JSON file referenced by MOONCAKE_CONFIG_PATH.

Common situations: Copy-pasting a mooncake config from another deployment/docs that uses a different mode vocabulary; mooncake upstream renaming modes between versions.

Related errors

• Mooncake preferred_segment override must be a non-empty stri
• local_buffer_size must be > 0
• embedded mode requires global_segment_size > 0
• standalone-store mode requires global_segment_size == 0
• Unknown dtype: {dtype!r}

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