sgl-project/sglang · error · ValueError

Unknown CacheAgnostic Policy: {policy=}

Error message

Unknown CacheAgnostic Policy: {policy=}

What it means

The cache-agnostic branch of SchedulePolicy.calc_priority failed to match the policy against FCFS, LOF, RANDOM, or ROUTING_KEY, so the waiting-queue sort dispatch aborts.

Source

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

                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:
        if self.policy == CacheAwarePolicy.LPM and len(waiting_queue) > 128:
            # Turn off the expensive prefix matching and sorting when the #queue is large.
            return CacheAgnosticPolicy.FCFS
        return self.policy

    def waiting_queue_prefix_matched(self, waiting_queue: List[Req]) -> bool:
        policy = self._determine_active_policy(waiting_queue)
        return (
            isinstance(policy, CacheAwarePolicy)
            or self.tree_cache.supports_fast_match_prefix()
        )

    def _validate_and_adjust_policy(
        self, policy: str, tree_cache: BasePrefixCache
    ) -> Policy:
        """

View on GitHub (pinned to 0132848349)

Solutions

1. Verify --schedule-policy against CacheAgnosticPolicy members (fcfs, lof, random, routing-key)
2. Check that _validate_and_adjust_policy correctly maps the string to an enum
3. Add the missing elif branch if you extended the enum in a fork

from sglang.srt.managers.schedule_policy import CacheAgnosticPolicy
valid = {p.value for p in CacheAgnosticPolicy} | {p.value for p in CacheAwarePolicy}
assert policy in valid

When it happens

Trigger: A policy that is neither a CacheAwarePolicy nor one of the known CacheAgnosticPolicy values reaches calc_priority; e.g. a new or misspelled policy string passed via schedule_policy.

Common situations: Version drift between the policy list accepted by _validate_and_adjust_policy / CLI and the branches handled here; custom forks adding policies without updating the dispatch.

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 CacheAware 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/492fdd3ae264e112. Report an issue: GitHub.