sgl-project/sglang · error · ValueError

Unknown CacheAware Policy: {policy=}

Error message

Unknown CacheAware Policy: {policy=}

What it means

Thrown by SchedulePolicy.calc_priority when the configured policy was recognized as a CacheAwarePolicy variant but did not match any known CacheAwarePolicy enum member (LPM, DFS_WEIGHT). It signals an unrecognized cache-aware scheduling policy string reached the sort dispatch.

Source

Thrown at python/sglang/srt/managers/schedule_policy.py:272

        if self.policy == CacheAgnosticPolicy.FCFS:
            if self.enable_priority_scheduling:
                SchedulePolicy._sort_by_priority_and_fcfs(
                    waiting_queue, self.priority_sign
                )
            return

        if isinstance(policy, CacheAwarePolicy):
            temporary_deprioritized = self._compute_prefix_matches(
                waiting_queue, policy
            )
            if policy == CacheAwarePolicy.LPM:
                SchedulePolicy._sort_by_longest_prefix(
                    waiting_queue, temporary_deprioritized
                )
            elif policy == CacheAwarePolicy.DFS_WEIGHT:
                SchedulePolicy._sort_by_dfs_weight(waiting_queue, self.tree_cache)
            else:
                raise ValueError(f"Unknown CacheAware Policy: {policy=}")
        else:
            if policy == CacheAgnosticPolicy.FCFS:
                pass
            elif policy == CacheAgnosticPolicy.LOF:
                SchedulePolicy._sort_by_longest_output(
                    waiting_queue,
                    self.enable_priority_scheduling,
                    self.priority_sign,
                )
            elif policy == CacheAgnosticPolicy.RANDOM:
                SchedulePolicy._sort_randomly(waiting_queue)
            elif policy == CacheAgnosticPolicy.ROUTING_KEY:
                if running_batch is not None:
                    SchedulePolicy._sort_by_routing_key(waiting_queue, running_batch)
            else:
                raise ValueError(f"Unknown CacheAgnostic Policy: {policy=}")

    def _determine_active_policy(self, waiting_queue: List[Req]) -> Policy:

View on GitHub (pinned to 0132848349)

Solutions

1. Check the --schedule-policy value against CacheAwarePolicy enum members (lpm, dfs-weight)
2. Upgrade or align the client code with the sglang version whose enum set matches
3. If adding a new policy, implement its sort branch in calc_priority

Example fix

# before
python -m sglang.launch_server --schedule-policy cache_aware_typo
# after
python -m sglang.launch_server --schedule-policy lpm

from sglang.srt.managers.schedule_policy import CacheAwarePolicy
valid = {p.value for p in CacheAwarePolicy}
assert policy in valid, f'unknown cache-aware policy {policy}'

When it happens

Trigger: Passing a policy value to SchedulePolicy that parses as a CacheAwarePolicy branch but is not LPM or DFS_WEIGHT, e.g. via schedule_policy server arg or a custom policy string; reached through get_new_batch_prefill_raw / get_new_prebuilt_batch.

Common situations: Typos in --schedule-policy, using a policy name from an older/newer sglang version, or programmatic construction of SchedulePolicy with an invalid enum value.

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

• Unknown CacheAgnostic Policy: {policy=}
• rollout_sde_type must be one of {_VALID_ROLLOUT_SDE_TYPES},
• Invalid backend: {value}. Must be one of: {', '.join([m.valu
• Invalid attention backend '{backend}'. Available options are
• kv-canary: kv_canary must be one of none/log/raise, got {mod

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