sgl-project/sglang · error · ValueError

Invalid grammar backend: {name}

Error message

Invalid grammar backend: {name}

What it means

create_grammar_backend dispatches on the --grammar-backend name (e.g. 'xgrammar', 'llguidance', 'none'); any unrecognized name raises ValueError('Invalid grammar backend: {name}').

Source

Thrown at python/sglang/srt/constrained/base_grammar_backend.py:425

        grammar_backend = GuidanceBackend(
            tokenizer=tokenizer,
            any_whitespace=not get_serving().constrained_json_disable_any_whitespace,
            whitespace_pattern=get_serving().constrained_json_whitespace_pattern,
            n_vocab=vocab_size,
            eos_token_ids=eos_token_ids,
        )
    elif name == "none":
        if get_serving().enable_strict_thinking:
            raise ValueError(
                "--enable-strict-thinking requires a grammar backend that supports "
                "token filtering, but grammar_backend='none' was specified. Use "
                "--grammar-backend xgrammar or another backend that supports token "
                "filtering."
            )
        return None
    else:
        raise ValueError(f"Invalid grammar backend: {name}")

    if get_serving().reasoning_parser and think_end_ids:
        from sglang.srt.constrained.reasoner_grammar_backend import (
            ReasonerGrammarBackend,
        )

        reasoning_parser = ReasoningParser(
            model_type=get_serving().reasoning_parser,
            stream_reasoning=False,
            tokenizer=tokenizer,
        )

        grammar_backend = ReasonerGrammarBackend(
            grammar_backend,
            reasoning_parser,
            tokenizer,
            enable_strict_thinking=get_serving().enable_strict_thinking,
        )

View on GitHub (pinned to 0132848349)

Solutions

1. Check the valid choices in base_grammar_backend.create_grammar_backend (currently 'xgrammar', 'llguidance', 'none') and correct the flag
2. Omit --grammar-backend to use the default (xgrammar)
3. If you passed a custom backend object, verify you are using the code path that accepts callable backends, not the string CLI path

Example fix

# before
--grammar-backend outlines
# after
--grammar-backend xgrammar

VALID_BACKENDS = {'xgrammar', 'llguidance', 'none'}
assert server_args.grammar_backend in VALID_BACKENDS

When it happens

Trigger: Passing a misspelled or outdated backend name such as 'outlines', 'guidance', 'xgramar', or a backend removed in this version via --grammar-backend.

Common situations: Upgrading SGLang where a backend (e.g. outlines) was removed; typos in launch scripts; names from older documentation.

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

• --enable-strict-thinking requires a grammar backend that sup
• world_size ({world_size}) is less than tensor_parallel_degre
• --enable-strict-thinking requires a grammar backend with tok
• think_end_token '{reasoning_parser.detector.think_end_token}
• Strict reasoning format requested but the grammar backend do

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