sgl-project/sglang · error · ValueError

Unknown schedule_policy: {policy=}

Error message

Unknown schedule_policy: {policy=}

What it means

Raised in SchedulePolicy.__init__ via _validate_and_adjust_policy when the policy string is neither a valid CacheAwarePolicy nor CacheAgnosticPolicy enum value, meaning the scheduler cannot be constructed with it.

Source

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

        )

    def _validate_and_adjust_policy(
        self, policy: str, tree_cache: BasePrefixCache
    ) -> Policy:
        """
        Validates the policy and adjusts it if necessary based on tree cache settings.
        """
        try:
            policy_enum = CacheAwarePolicy(policy)
            if getattr(tree_cache, "disable", True):
                # If tree_cache is disabled, using CacheAgnosticPolicy policy
                return CacheAgnosticPolicy.FCFS
            return policy_enum
        except ValueError:
            try:
                return CacheAgnosticPolicy(policy)
            except ValueError:
                raise ValueError(f"Unknown schedule_policy: {policy=}")

    def _compute_prefix_matches(
        self, waiting_queue: List[Req], policy: CacheAwarePolicy
    ) -> Set[int]:
        """
        Computes and caches the matching prefixes for requests in the waiting queue,
            and handles in-batch prefix caching logic.
        """
        temporary_deprioritized: Set[int] = set()
        self.waiting_queue_radix_tree.reset()

        for r in waiting_queue:
            prefix_ids = r.origin_input_ids + r.output_ids
            extra_key = r.extra_key
            cache_salt = r.cache_salt
            match_result = match_prefix_for_req(
                self.tree_cache, r, prefix_ids, include_req=True
            )

View on GitHub (pinned to 0132848349)

Solutions

1. Use one of: fcfs, lpm, dfs-weight, lof, random, routing-key (exact, lowercase)
2. Print/inspect the accepted enum members from CacheAwarePolicy and CacheAgnosticPolicy for your installed version
3. Strip whitespace/quotes from the CLI value in launch scripts

Example fix

# before
--schedule-policy longest-prefix-match
# after
--schedule-policy lpm

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

try:
    SchedulePolicy(policy, tree_cache, ...)
except ValueError as e:
    if 'Unknown schedule_policy' in str(e):
        policy = 'fcfs'  # fallback
    else:
        raise

When it happens

Trigger: Launching the server or constructing SchedulePolicy with an unknown schedule_policy string (e.g. 'fcfs ' with whitespace, 'LPM' wrong case where not aliased, or a made-up name).

Common situations: Typos or case mistakes in --schedule-policy, copy-pasting flags from other engines (vLLM policy names), or version changes that renamed policies.

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

• Invalid threshold_type for topk: {threshold_type}. Choose 'q
• Invalid threshold_type: {threshold_type}. Choose 'query_head
• f"Unknown feature map: {feature_map}"
• f"Unsupported patch_size type: {type(patch_size)}"
• batching config rule requires max_batch_size

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