{"record":{"id":"6b8be252825b4d80","repo":"sgl-project/sglang","slug":"matcher-error","errorCode":null,"errorMessage":"{matcher_error}","messagePattern":"\\{matcher_error\\}","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/constrained/llguidance_backend.py","lineNumber":208,"sourceCode":"\n    def try_jump_forward(self, tokenizer) -> Optional[Tuple[List[int], str]]:\n        ff_tokens = self.ll_matcher.compute_ff_tokens()\n        if ff_tokens:\n            return ff_tokens, \"\"\n        else:\n            return None\n\n    def jump_forward_str_state(self, helper: Tuple[List[int], str]) -> Tuple[str, int]:\n        return \"\", -1\n\n    def jump_and_retokenize(\n        self, old_output_ids: List[int], new_output_ids: List[int], next_state: int\n    ):\n        pass\n\n    def _check_err(self) -> None:\n        if self.ll_matcher.is_error():\n            raise ValueError(self.ll_matcher.get_error())\n\n\nclass GuidanceBackend(BaseGrammarBackend):\n\n    def __init__(\n        self,\n        tokenizer,\n        any_whitespace: bool = True,\n        whitespace_pattern: Optional[str] = None,\n        n_vocab: Optional[int] = None,\n        eos_token_ids: Optional[Union[int, Iterable[int]]] = None,\n    ):\n        super().__init__()\n\n        self.tokenizer = tokenizer\n        self.any_whitespace = any_whitespace\n        self.whitespace_pattern = whitespace_pattern\n        self.llguidance_tokenizer = from_tokenizer(","sourceCodeStart":190,"sourceCodeEnd":226,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/constrained/llguidance_backend.py#L190-L226","documentation":"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).","triggerScenarios":"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.","commonSituations":"Passing invalid JSON-schema regex patterns, unsupported character classes, or a grammar string with syntax errors via structured output requests; llguidance version behavior changes.","solutions":["Inspect the matcher error text — it usually pinpoints the grammar line/construct","Validate the grammar (regex/JSON schema) with llguidance directly or a regex tool before sending requests","Simplify the schema (avoid exotic regex features) or switch --grammar-backend xgrammar to compare behavior","Upgrade llguidance if the error is a known bug"],"exampleFix":"// before\n{\"regex\": \"(?P<name>...)\"}  // named groups unsupported\n// after\n{\"regex\": \"[A-Za-z]+\"}","handlingStrategy":"try-catch","validationCode":"import llguidance\nllguidance.Grammar(raw=json.dumps(schema))  # raises early on bad grammar","typeGuard":null,"tryCatchPattern":"try:\n    bitmasks = backend.fill_vocab_mask(request)\nexcept ValueError as e:\n    return error_response(f'invalid grammar: {e}')","preventionTips":["Lint user-supplied JSON schemas/regexes before they reach the scheduler","Keep a corpus of known-good schemas for regression testing"],"tags":["grammar","llguidance","structured-output"],"backgroundTag":"grammar-compilation-failed","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}