{"record":{"id":"176a435dd2f43822","repo":"vllm-project/vllm","slug":"embedded-mode-requires-global-segment-size-0","errorCode":null,"errorMessage":"embedded mode requires global_segment_size > 0","messagePattern":"embedded mode requires global_segment_size > 0","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/worker.py","lineNumber":146,"sourceCode":"    \"\"\"\n\n    metadata_server: str\n    master_server_address: str\n    protocol: str\n    device_name: str\n    mode: MooncakeMode = \"embedded\"\n    global_segment_size: int = DEFAULT_GLOBAL_SEGMENT_SIZE\n    local_buffer_size: int = DEFAULT_LOCAL_BUFFER_SIZE\n    enable_offload: bool = False\n    tenant_id: str = DEFAULT_TENANT_ID\n\n    def __post_init__(self) -> None:\n        if self.mode not in (\"embedded\", \"standalone-store\"):\n            raise ValueError(f\"unknown Mooncake mode: {self.mode!r}\")\n        if self.local_buffer_size <= 0:\n            raise ValueError(\"local_buffer_size must be > 0\")\n        if self.mode == \"embedded\" and self.global_segment_size == 0:\n            raise ValueError(\"embedded mode requires global_segment_size > 0\")\n        if self.mode == \"standalone-store\" and self.global_segment_size != 0:\n            raise ValueError(\"standalone-store mode requires global_segment_size == 0\")\n\n    @staticmethod\n    def from_file(file_path: str) -> \"MooncakeStoreConfig\":\n        with open(file_path) as file:\n            config = json.load(file)\n        return MooncakeStoreConfig(\n            metadata_server=config.get(\"metadata_server\", \"\"),\n            master_server_address=config.get(\"master_server_address\", \"\"),\n            protocol=config.get(\"protocol\", \"rdma\"),\n            device_name=config.get(\"device_name\", \"\"),\n            mode=config.get(\"mode\", \"embedded\"),\n            global_segment_size=_parse_size(\n                config.get(\"global_segment_size\", DEFAULT_GLOBAL_SEGMENT_SIZE)\n            ),\n            local_buffer_size=_parse_size(\n                config.get(\"local_buffer_size\", DEFAULT_LOCAL_BUFFER_SIZE)","sourceCodeStart":128,"sourceCodeEnd":164,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/worker.py#L128-L164","documentation":"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).","triggerScenarios":"\"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.","commonSituations":"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.","solutions":["Set a positive global segment size for embedded mode, e.g. \"8GB\", sized to the KV you expect to serve from memory","Or switch to \"mode\": \"standalone-store\" (then global_segment_size must be 0 and an external store service is used)"],"exampleFix":"// before\n{ \"mode\": \"embedded\", \"global_segment_size\": \"0\" }\n\n// after\n{ \"mode\": \"embedded\", \"global_segment_size\": \"8GB\" }","handlingStrategy":"validation","validationCode":"mode, gs = raw.get(\"mode\", \"embedded\"), _parse_size(raw.get(\"global_segment_size\", DEFAULT))\nif mode == \"embedded\" and gs == 0:\n    raise ValueError(\"embedded mode needs global_segment_size > 0\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat (mode, global_segment_size) as one coupled decision, not two fields","Validate the pair in a preflight config check in CI"],"tags":["mooncake","config","rdma","validation"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}