vllm-project/vllm · error · ValueError

embedded mode requires global_segment_size > 0

Error message

embedded mode requires global_segment_size > 0

What it means

In embedded mode the mooncake store allocates a global RDMA segment inside the vLLM worker, so global_segment_size must be non-zero. __post_init__ rejects global_segment_size == 0 when mode == 'embedded' (0 is only legal for standalone-store, where the segment lives in the external service).

Source

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

    """

    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(
                config.get("global_segment_size", DEFAULT_GLOBAL_SEGMENT_SIZE)
            ),
            local_buffer_size=_parse_size(
                config.get("local_buffer_size", DEFAULT_LOCAL_BUFFER_SIZE)

View on GitHub (pinned to c794754062)

Solutions

1. Set a positive global segment size for embedded mode, e.g. "8GB", sized to the KV you expect to serve from memory
2. Or switch to "mode": "standalone-store" (then global_segment_size must be 0 and an external store service is used)

Example fix

// before
{ "mode": "embedded", "global_segment_size": "0" }

// after
{ "mode": "embedded", "global_segment_size": "8GB" }

mode, gs = raw.get("mode", "embedded"), _parse_size(raw.get("global_segment_size", DEFAULT))
if mode == "embedded" and gs == 0:
    raise ValueError("embedded mode needs global_segment_size > 0")

When it happens

Trigger: "mode": "embedded" together with "global_segment_size": 0 or "0GB" in the config file, or omitting/typo-ing the key so _parse_size yields 0.

Common situations: Reusing a standalone-store config but flipping only the mode field; size string with an unparseable suffix falling back to 0 in an older config.

Related errors

• Mooncake preferred_segment override must be a non-empty stri
• 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/176a435dd2f43822. Report an issue: GitHub.