{"record":{"id":"388d5676a347e1fb","repo":"sgl-project/sglang","slug":"mp-mode-requires-lmcache-config-file-the-yaml-s","errorCode":null,"errorMessage":"MP mode requires --lmcache-config-file (the YAML supplies mp_host / mp_port).","messagePattern":"MP mode requires --lmcache-config-file \\(the YAML supplies mp_host / mp_port\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/mem_cache/storage/lmcache/lmc_radix_cache.py","lineNumber":144,"sourceCode":"            ),\n            v_pool=getattr(\n                kvcache,\n                \"v_buffer\",\n                getattr(self.token_to_kv_pool_allocator._kvcache, \"v_buffer\"),\n            ),\n            tp_group=tp_group.device_group if tp_group is not None else None,\n        )\n\n        self.load_stream = create_device_stream(self.device)\n        self.store_stream = create_device_stream(self.device)\n\n        # MP (multi-process) is the default. XPU defaults to IP (in-process\n        # layerwise) because the MP connector shares the KV cache via CUDA IPC\n        # (``Tensor._share_cuda_``), which is unavailable on XPU.\n        self._mode = LMCacheMode.IP if self.device.type == \"xpu\" else LMCacheMode.MP\n        if self._mode is LMCacheMode.MP:\n            if not cli_lmc_cfg:\n                raise ValueError(\n                    \"MP mode requires --lmcache-config-file (the YAML \"\n                    \"supplies mp_host / mp_port).\"\n                )\n            lm_cfg = lmcache_get_config(cli_lmc_cfg)\n            self.lmcache_connector = LMCacheMPConnector(\n                page_size=params.page_size,\n                host=lm_cfg.mp_host,\n                port=lm_cfg.mp_port,\n                **connector_kwargs,\n            )\n        elif self._mode is LMCacheMode.IP:\n            self.lmcache_connector = LMCacheLayerwiseConnector(\n                config_file=cli_lmc_cfg, **connector_kwargs\n            )\n            # Per-layer hook\n            self.layer_done_executor = LayerTransferCounter(\n                num_layers=(\n                    model_config.num_hidden_layers if model_config is not None else 0","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/mem_cache/storage/lmcache/lmc_radix_cache.py#L126-L162","documentation":"LMCacheRadixCache defaults to MP mode (multi-process, using LMCacheMPConnector) except on XPU. MP mode requires the CLI --lmcache-config-file because the YAML it points to supplies mp_host/mp_port for the connector's endpoint; without cli_lmc_cfg, __init__ raises ValueError.","triggerScenarios":"Constructing LMCacheRadixCache on a CUDA device without passing the lmcache config file (cli_lmc_cfg is None) — e.g. enabling LMCache via server args/env without --lmcache-config-file.","commonSituations":"Switching from the old IP/layerwise integration (no config file needed) to the new default MP mode after an upgrade; config file flag forgotten in launch scripts; XPU deployment changed to GPU without adding the YAML.","solutions":["Pass --lmcache-config-file /path/to/lmcache.yaml when launching the server, with mp_host/mp_port set in the YAML","If you intended in-process layerwise mode, use an XPU device or explicitly configure the IP mode path supported by your version","Update launch scripts/checklists — MP is now the default on non-XPU devices"],"exampleFix":"# before\npython -m sglang.launch_server --model ... --enable-lmcache\n\n# after\npython -m sglang.launch_server --model ... --enable-lmcache \\\n  --lmcache-config-file /etc/sglang/lmcache.yaml  # contains mp_host/mp_port","handlingStrategy":"validation","validationCode":"if device.type != 'xpu':\n    assert cli_lmc_cfg, 'MP mode needs --lmcache-config-file with mp_host/mp_port'\ncache = LMCacheRadixCache(params, device, cli_lmc_cfg=cli_lmc_cfg, ...)","typeGuard":null,"tryCatchPattern":"try:\n    cache = LMCacheRadixCache(params, device)\nexcept ValueError as e:\n    if 'MP mode requires --lmcache-config-file' in str(e):\n        raise SystemExit('add --lmcache-config-file lmcache.yaml (with mp_host/mp_port)')\n    raise","preventionTips":["Always pass --lmcache-config-file when enabling LMCache on GPU (non-XPU) after upgrades","Keep mp_host/mp_port filled in the YAML; validate it in a preflight script"],"tags":["lmcache","mp-mode","missing-config","server-args"],"backgroundTag":"missing-config-file","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}