{"record":{"id":"6d022b8cf1cf3993","repo":"sgl-project/sglang","slug":"hicache-host-memory-mode-must-be-cache-or-buffe","errorCode":null,"errorMessage":"hicache_host_memory_mode must be 'cache' or 'buffer_only', got {cfg.hicache_host_memory_mode!r}","messagePattern":"hicache_host_memory_mode must be 'cache' or 'buffer_only', got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/server_args.py","lineNumber":8297,"sourceCode":"            )\n        ):\n            return\n\n        self._validate_hicache_host_memory_mode()\n\n        # Step 1: Initial layout-io compatibility normalization.\n        self._resolve_layout_io_compatibility()\n\n        # Step 2: Storage-layout normalization without changing io backend.\n        self._resolve_storage_layout_compatibility()\n\n        # Step 3: DCP compatibility for the L2 (device<->host) path.\n        self._resolve_hicache_dcp_compatibility()\n\n    def _validate_hicache_host_memory_mode(self):\n        cfg = resolving_view(self)\n        if cfg.hicache_host_memory_mode not in (\"cache\", \"buffer_only\"):\n            raise ValueError(\n                \"hicache_host_memory_mode must be 'cache' or 'buffer_only', \"\n                f\"got {cfg.hicache_host_memory_mode!r}\"\n            )\n\n        # Both modes are defaulted upstream (a decode server resolves the\n        # ratio later, in kv_cache_builder), so this fires only if that\n        # defaulting regresses -- never build an unsized host pool.\n        if (\n            cfg.hicache_size <= 0\n            and cfg.hicache_ratio is None\n            and cfg.disaggregation_mode != \"decode\"\n        ):\n            raise ValueError(\n                f\"--hicache-host-memory-mode {cfg.hicache_host_memory_mode} \"\n                \"requires a host pool size: pass --hicache-size or \"\n                \"--hicache-ratio.\"\n            )\n","sourceCodeStart":8279,"sourceCodeEnd":8315,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/server_args.py#L8279-L8315","documentation":"SGLang's HiCache host memory accepts exactly two modes: 'cache' (host memory as a caching tier) and 'buffer_only' (host memory as a plain staging buffer). _validate_hicache_host_memory_mode rejects any other value of --hicache-host-memory-mode before the server starts.","triggerScenarios":"Passing --hicache-host-memory-mode with a typo'd or unsupported value (anything outside {\"cache\",\"buffer_only\"}), e.g. buffer, host_cache, or none.","commonSituations":"Typos in launch scripts, stale flags from older versions where the option did not exist or had different names, or copying configs between SGLang versions.","solutions":["Correct the value to exactly 'cache' or 'buffer_only'","Remove the flag to use the default mode","Check the current --help output for the accepted enum values of your SGLang version"],"exampleFix":"# before\n--hicache-host-memory-mode buffer\n# after\n--hicache-host-memory-mode buffer_only","handlingStrategy":"type-guard","validationCode":"VALID_HICACHE_HOST_MODES = {\"cache\", \"buffer_only\"}\nmode = parsed.get(\"hicache_host_memory_mode\")\nif mode is not None and mode not in VALID_HICACHE_HOST_MODES:\n    raise SystemExit(f\"hicache_host_memory_mode must be one of {sorted(VALID_HICACHE_HOST_MODES)}\")","typeGuard":"def is_valid_hicache_host_mode(mode: str) -> bool:\n    return mode in {\"cache\", \"buffer_only\"}","tryCatchPattern":null,"preventionTips":["Validate enum flags against a whitelist before launching the server","Generate launch configs from typed/validated config files instead of raw shell strings","Check sglang --help after version upgrades for renamed or narrowed enum values"],"tags":["sglang","hicache","host-memory","config-validation","server-args"],"backgroundTag":"invalid-enum-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}