sgl-project/sglang · error · ValueError

cache_salt is not supported by the experimental C++ radix tr

Error message

cache_salt is not supported by the experimental C++ radix tree

What it means

RadixCacheCpp (the experimental C++ radix tree) rejects cache_salt entirely — any non-None salt raises ValueError at match_prefix, cache_finished_req, and cache_unfinished_req. The C++ tree has no salt-namespacing support yet, so this is a deliberate capability gate rather than a bug.

Source

Thrown at python/sglang/srt/mem_cache/radix_cache_cpp.py:42

from sglang.srt.mem_cache.radix_cache import RadixKey
from sglang.srt.runtime_context import (
    get_memory,
)

if TYPE_CHECKING:
    from sglang.srt.managers.schedule_batch import Req
    from sglang.srt.mem_cache.cache_init_params import CacheInitParams
    from sglang.srt.server_args import ServerArgs


logger = logging.getLogger(__name__)


class RadixCacheCpp(BasePrefixCache):
    @staticmethod
    def _reject_cache_salt(cache_salt: Optional[str]) -> None:
        if cache_salt is not None:
            raise ValueError(
                "cache_salt is not supported by the experimental C++ radix tree"
            )

    def __init__(
        self,
        params: CacheInitParams,
        server_args: ServerArgs,
        enable_write_cancel: bool = False,
    ):
        self.disable = params.disable
        self.enable_write_cancel = enable_write_cancel

        assert (
            params.enable_kv_cache_events is False
        ), "HiRadixCache does not support kv cache events yet"

        # record the nodes with ongoing write through
        self.ongoing_write_through: Set[IOHandle] = set()

View on GitHub (pinned to 0132848349)

Solutions

Remove/disable cache_salt for this deployment, or
Switch back to the default Python radix cache backend which supports cache_salt
Wait for / implement cache_salt support in the C++ tree before enabling it

Example fix

# before
server_args.radix_cache_backend = "cpp"
# requests carry cache_salt='tenant-a'
# after
server_args.radix_cache_backend = None  # default python RadixCache supports salt

Defensive patterns

Strategy: validation

Validate before calling

if using_cpp_tree and requests_have_cache_salt:
    raise ValueError("cache_salt unsupported by C++ radix tree; drop salt or switch backend")

Prevention

Check feature matrix before combining experimental backends with salting
Fail fast at startup by probing a match_prefix with the salt

When it happens

Trigger: Selecting the C++ backend (e.g. --radix-cache-backend with the cpp/'Flash' backend) while requests carry a cache_salt (from multi-tenant salting or --cache-salt style config), then any prefix op on the tree.

Common situations: Enabling the experimental C++ radix tree for speed on a deployment that already uses cache_salt; setting a global salt via server args and forgetting the C++ tree does not implement it.

Related errors

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