{"record":{"id":"ba0d16bbc07887a5","repo":"sgl-project/sglang","slug":"unknown-retraction-backup-backend-backend","errorCode":null,"errorMessage":"Unknown retraction backup backend: {backend}","messagePattern":"Unknown retraction backup backend: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/mem_cache/common.py","lineNumber":158,"sourceCode":"            tree_cache.evict_for_alloc(\n                EvictParams(num_tokens=num_tokens - available_size)\n            )\n\n\ndef retraction_backup(\n    req: Req,\n    tree_cache: BasePrefixCache,\n    req_to_token_pool: ReqToTokenPool,\n    token_to_kv_pool_allocator: BaseTokenToKVPoolAllocator,\n    backend: str,\n) -> bool:\n    \"\"\"Returns False when the host pool cannot hold the backup; the caller\n    aborts the request since its KV cannot be preserved.\"\"\"\n    if backend == \"cpu_tensor\":\n        req.offload_kv_cache(req_to_token_pool, token_to_kv_pool_allocator)\n        return True\n    if backend != \"host_pool\":\n        raise ValueError(f\"Unknown retraction backup backend: {backend}\")\n    if req.seqlen <= 1:\n        return True\n\n    unified_cache = cast(\"UnifiedRadixCache\", tree_cache)\n    req.retraction_backup = unified_cache.retraction_backup(req)\n    return req.retraction_backup is not None\n\n\ndef retraction_restore(\n    req: Req,\n    tree_cache: BasePrefixCache,\n    req_to_token_pool: ReqToTokenPool,\n    token_to_kv_pool_allocator: BaseTokenToKVPoolAllocator,\n    backend: str,\n) -> None:\n    if backend == \"cpu_tensor\":\n        req.load_kv_cache(req_to_token_pool, token_to_kv_pool_allocator)\n        return","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/mem_cache/common.py#L140-L176","documentation":"Retraction backup dispatch in the host memory cache received a backend string other than 'cpu_tensor' or 'host_pool'. This is an internal config-plumbing error: the backend name is not a user-facing enum and only those two implementations exist.","triggerScenarios":"Calling retraction_backup with a backend string that isn't 'cpu_tensor' or 'host_pool'; typically from custom server args or a fork that passes a new backend name without implementing it.","commonSituations":"Typos in backend configuration ('host-pool', 'hostpool'); code changes that rename the backend constant; third-party patches adding a backend but routing through the old dispatcher.","solutions":["Set the backend to one of the supported values: 'cpu_tensor' or 'host_pool'","Check where the backend string originates (server args / scheduler config) and fix the typo or mapping","If you need a new backend, implement the branch in retraction_backup/restore/discard rather than passing an unknown name"],"exampleFix":"# before\nbackend = \"host-pool\"\n# after\nbackend = \"host_pool\"","handlingStrategy":"validation","validationCode":"assert backend in (\"cpu_tensor\", \"host_pool\"), f\"bad retraction backend: {backend!r}\"","typeGuard":"from typing import Literal\nRetractionBackend = Literal[\"cpu_tensor\", \"host_pool\"]\ndef is_valid_backend(b: str) -> bool: return b in (\"cpu_tensor\", \"host_pool\")","tryCatchPattern":null,"preventionTips":["Define one module-level constant for the backend string and reuse it at all call sites","Validate backend once at config load, not per retraction event"],"tags":["retraction","backend-dispatch","invalid-value","internal"],"backgroundTag":"invalid-enum-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}