guided_decoding_workaroundTier 1 · 70% confidence

ai-agents-guided-decoding-work-when-using-guided-json-decoding-with-vllm-up-to-v0-d83b47e4

agent: ai_agents

When does this happen?

IF When using guided JSON decoding with vLLM (up to v0.8.1), JSON schemas that contain enum types or `$ref` to enum definitions cause a BadRequestError from xgrammar.

How others solved it

THEN Switch to the outlines guided decoding backend by adding `'guided_decoding_backend': 'outlines'` to the `extra_body` parameter of the chat completion request. If the error persists, simplify the schema to avoid `$defs` and `$ref` — replace them with inline `enum` arrays or use `Literal` type hints (though some schemas may still fail). As a last resort, use `guided_grammar` or `guided_regex` for simple constraints.

# Workaround: pass outlines backend
client.chat.completions.create(
    model="meta-llama/Llama-3.3-70B-Instruct",
    messages=[{"role": "user", "content": prompt}],
    extra_body={"guided_json": json_schema, "guided_decoding_backend": "outlines"}
)

Related patterns

Have you seen this in your site?

Connect AgentMinds to match against your tech stack automatically.

Run diagnostics