{"record":{"id":"1b1dc4873bcb3afc","repo":"vllm-project/vllm","slug":"local-buffer-size-must-be-0","errorCode":null,"errorMessage":"local_buffer_size must be > 0","messagePattern":"local_buffer_size must be > 0","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/worker.py","lineNumber":144,"sourceCode":"    contributes 0; an external ``mooncake_client`` process owns the pool\n    and the SSD tier).\n    \"\"\"\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            ),","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/worker.py#L126-L162","documentation":"MooncakeStoreConfig requires local_buffer_size (the per-worker staging buffer for KV transfer) to be a positive byte count. It is parsed from the config file via _parse_size, so 0, a negative number, or a string like \"0GB\"/'-1' fails validation in __post_init__.","triggerScenarios":"\"local_buffer_size\": 0 / -1 / \"0KB\" in the mooncake store config file.","commonSituations":"Disabling the buffer by zeroing it (not supported — it is mandatory); size strings with typos that parse to 0; minimal/test configs copied from examples with tiny values.","solutions":["Set local_buffer_size to a positive size appropriate for your largest batch of KV blocks, e.g. \"1GB\" or 1073741824","If you intended to reduce memory, lower it gradually (e.g. 64MB) rather than to zero"],"exampleFix":"// before\n{ \"local_buffer_size\": \"0\" }\n\n// after\n{ \"local_buffer_size\": \"1GB\" }","handlingStrategy":"validation","validationCode":"sz = raw.get(\"local_buffer_size\")\nparsed = _parse_size(sz) if isinstance(sz, (int, str)) else int(sz)\nif parsed <= 0:\n    raise ValueError(\"local_buffer_size must parse to a positive byte count\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never zero the staging buffer to 'disable' it — size it to your batch instead","Use unit strings (\"512MB\") for readability and lint them in config checks"],"tags":["mooncake","config","validation"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}