sgl-project/sglang · error · ValueError

{matcher_error}

Error message

{matcher_error}

What it means

The LLGuidance adapter checks the underlying matcher after every operation; if ll_matcher.is_error() is set, _check_err raises ValueError with the error string returned by the llguidance engine (grammar compile or runtime automaton error).

Source

Thrown at python/sglang/srt/constrained/llguidance_backend.py:208

    def try_jump_forward(self, tokenizer) -> Optional[Tuple[List[int], str]]:
        ff_tokens = self.ll_matcher.compute_ff_tokens()
        if ff_tokens:
            return ff_tokens, ""
        else:
            return None

    def jump_forward_str_state(self, helper: Tuple[List[int], str]) -> Tuple[str, int]:
        return "", -1

    def jump_and_retokenize(
        self, old_output_ids: List[int], new_output_ids: List[int], next_state: int
    ):
        pass

    def _check_err(self) -> None:
        if self.ll_matcher.is_error():
            raise ValueError(self.ll_matcher.get_error())


class GuidanceBackend(BaseGrammarBackend):

    def __init__(
        self,
        tokenizer,
        any_whitespace: bool = True,
        whitespace_pattern: Optional[str] = None,
        n_vocab: Optional[int] = None,
        eos_token_ids: Optional[Union[int, Iterable[int]]] = None,
    ):
        super().__init__()

        self.tokenizer = tokenizer
        self.any_whitespace = any_whitespace
        self.whitespace_pattern = whitespace_pattern
        self.llguidance_tokenizer = from_tokenizer(

View on GitHub (pinned to 0132848349)

Solutions

1. Inspect the matcher error text — it usually pinpoints the grammar line/construct
2. Validate the grammar (regex/JSON schema) with llguidance directly or a regex tool before sending requests
3. Simplify the schema (avoid exotic regex features) or switch --grammar-backend xgrammar to compare behavior
4. Upgrade llguidance if the error is a known bug

Example fix

// before
{"regex": "(?P<name>...)"}  // named groups unsupported
// after
{"regex": "[A-Za-z]+"}

import llguidance
llguidance.Grammar(raw=json.dumps(schema))  # raises early on bad grammar

try:
    bitmasks = backend.fill_vocab_mask(request)
except ValueError as e:
    return error_response(f'invalid grammar: {e}')

When it happens

Trigger: Compiling or advancing an LLGuidance grammar whose regex/EBNF is malformed, uses constructs llguidance does not support, or the matcher entering an error state after accept_token/rollback/fill_vocab_mask.

Common situations: Passing invalid JSON-schema regex patterns, unsupported character classes, or a grammar string with syntax errors via structured output requests; llguidance version behavior changes.

Related errors

• Grammar mask max_rows must be positive, got {max_rows}
• --enable-strict-thinking requires a grammar backend with tok
• --enable-strict-thinking requires a grammar backend that sup
• Invalid grammar backend: {name}
• think_end_token '{reasoning_parser.detector.think_end_token}

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