sgl-project/sglang · error · ValueError

--cuda-graph-config[{phase}].backend={backend!r} not allowed

Error message

--cuda-graph-config[{phase}].backend={backend!r} not allowed; allowed: {ALLOWED_BACKENDS_PER_PHASE[phase]}

What it means

Each CUDA graph phase (e.g. prefill/decode) in --cuda-graph-config only permits a fixed set of graph backends (ALLOWED_BACKENDS_PER_PHASE). Passing a backend name not in that phase's allowlist raises this error during config validation.

Source

Thrown at python/sglang/srt/server_args.py:5220

            "FlashAttention fallback that regresses prefill). Set the prefill cuda graph "
            "backend explicitly (e.g. --cuda-graph-backend-prefill tc_piecewise) to override.",
            cfg.cuda_graph_config.prefill.backend,
        )
        self._declare(
            "_disable_prefill_cuda_graph_for_deepseek_trtllm_mla",
            cuda_graph_config=with_phase(
                cfg.cuda_graph_config, Phase.PREFILL, backend=Backend.DISABLED
            ),
        )

    def _validate_cuda_graph_config(self):
        cfg = resolving_view(self)
        if cfg.cuda_graph_config is None:
            return
        for phase in Phase.ALL:
            backend = getattr(cfg.cuda_graph_config, phase).backend
            if backend not in ALLOWED_BACKENDS_PER_PHASE[phase]:
                raise ValueError(
                    f"--cuda-graph-config[{phase}].backend={backend!r} not allowed; "
                    f"allowed: {ALLOWED_BACKENDS_PER_PHASE[phase]}"
                )

    def _handle_multi_item_scoring(self):
        """Setup and validate multi-item scoring constraints.

        Auto-disables settings incompatible with MIS mechanics (CUDA graph,
        radix cache, chunked prefill). Asserts on attention backend since
        changing it silently could surprise users who intentionally picked
        a non-flashinfer backend.
        """
        cfg = resolving_view(self)
        if not cfg.enable_mis:
            return

        if cfg.cuda_graph_config.decode.backend != Backend.DISABLED:
            logger.warning("CUDA graph is disabled because --enable-mis is set.")

View on GitHub (pinned to 0132848349)

Solutions

1. Check ALLOWED_BACKENDS_PER_PHASE[phase] in python/sglang/srt/server_args.py and use one of those exact names
2. Use the default backend per phase by omitting the backend field
3. Re-check config examples for your SGLang version after upgrading

Example fix

# before
--cuda-graph-config '{"prefill": {"backend": "full"}}'
# after
--cuda-graph-config '{"prefill": {"backend": "<allowed prefill backend>"}}'

from sglang.srt.server_args import ALLOWED_BACKENDS_PER_PHASE
for phase in Phase.ALL:
    backend = cfg[phase]["backend"]
    assert backend in ALLOWED_BACKENDS_PER_PHASE[phase], f"{phase}: {backend} not allowed"

When it happens

Trigger: Setting --cuda-graph-config with a backend (e.g. 'piecewise' or 'full') that is not allowed for the given phase, or misspelling a backend name.

Common situations: Copy-pasting a decode-phase config into the prefill phase, version upgrades that renamed/removed backends, or typos in the JSON/YAML config.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• --bcg-text-buckets must contain at least one positive intege
• capacity must be positive, got {capacity}
• min_hits must be positive, got {min_hits}
• max_seqlen must be positive, got {max_seqlen}
• bad compress_ratio {compress_ratio}

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