sgl-project/sglang · error · ValueError

Unknown retraction backup backend: {backend}

Error message

Unknown retraction backup backend: {backend}

What it means

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.

Source

Thrown at python/sglang/srt/mem_cache/common.py:158

            tree_cache.evict_for_alloc(
                EvictParams(num_tokens=num_tokens - available_size)
            )


def retraction_backup(
    req: Req,
    tree_cache: BasePrefixCache,
    req_to_token_pool: ReqToTokenPool,
    token_to_kv_pool_allocator: BaseTokenToKVPoolAllocator,
    backend: str,
) -> bool:
    """Returns False when the host pool cannot hold the backup; the caller
    aborts the request since its KV cannot be preserved."""
    if backend == "cpu_tensor":
        req.offload_kv_cache(req_to_token_pool, token_to_kv_pool_allocator)
        return True
    if backend != "host_pool":
        raise ValueError(f"Unknown retraction backup backend: {backend}")
    if req.seqlen <= 1:
        return True

    unified_cache = cast("UnifiedRadixCache", tree_cache)
    req.retraction_backup = unified_cache.retraction_backup(req)
    return req.retraction_backup is not None


def retraction_restore(
    req: Req,
    tree_cache: BasePrefixCache,
    req_to_token_pool: ReqToTokenPool,
    token_to_kv_pool_allocator: BaseTokenToKVPoolAllocator,
    backend: str,
) -> None:
    if backend == "cpu_tensor":
        req.load_kv_cache(req_to_token_pool, token_to_kv_pool_allocator)
        return

View on GitHub (pinned to 0132848349)

Solutions

1. Set the backend to one of the supported values: 'cpu_tensor' or 'host_pool'
2. Check where the backend string originates (server args / scheduler config) and fix the typo or mapping
3. If you need a new backend, implement the branch in retraction_backup/restore/discard rather than passing an unknown name

Example fix

# before
backend = "host-pool"
# after
backend = "host_pool"

assert backend in ("cpu_tensor", "host_pool"), f"bad retraction backend: {backend!r}"

from typing import Literal
RetractionBackend = Literal["cpu_tensor", "host_pool"]
def is_valid_backend(b: str) -> bool: return b in ("cpu_tensor", "host_pool")

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• {self._op_label()}: no triton backend
• Unsupported sol_attn dense_backend={dense_backend!r}; expect
• Invalid ltx2_two_stage_device_mode={mode!r}. Expected one of
• queued MiniMax H3 jobs require pre-queue resolved_v2 geometr
• queued MiniMax H3 jobs require pre-queue resolved temporal d

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/ba0d16bbc07887a5. Report an issue: GitHub.