vllm-project/vllm · error · ValueError

disable_any_whitespace is only supported for xgrammar and gu

Error message

disable_any_whitespace is only supported for xgrammar and guidance backends.

What it means

StructuredOutputsConfig validates that disable_any_whitespace is only combined with the 'xgrammar' or 'guidance' structured-output backends. The flag instructs the grammar engine to forbid any whitespace in the generated output, and only those two backends implement that constraint in their grammar compilation. Requesting it with 'outlines', 'lm-format-enforcer', or no backend (auto-resolved elsewhere) fails fast at config validation.

Source

Thrown at vllm/config/structured_outputs.py:65

        ensure that it is included in the factors list if
        it affects the computation graph.

        Provide a hash that uniquely identifies all the configs
        that affect the structure of the computation
        graph from input ids/embeddings to the final hidden states,
        excluding anything before input ids/embeddings and after
        the final hidden states.
        """
        # no factors to consider.
        # this config will not affect the computation graph.
        factors: list[Any] = []
        hash_str = safe_hash(str(factors).encode(), usedforsecurity=False).hexdigest()
        return hash_str

    @model_validator(mode="after")
    def _validate_structured_output_config(self) -> Self:
        if self.disable_any_whitespace and self.backend not in ("xgrammar", "guidance"):
            raise ValueError(
                "disable_any_whitespace is only supported for "
                "xgrammar and guidance backends."
            )
        if self.disable_additional_properties and self.backend != "guidance":
            raise ValueError(
                "disable_additional_properties is only supported "
                "for the guidance backend."
            )
        return self

View on GitHub (pinned to c794754062)

Solutions

Set backend='xgrammar' or backend='guidance' in the structured outputs config
Remove disable_any_whitespace (accept default whitespace-tolerant behavior) if you must keep another backend
Post-validate whitespace on the application side if you cannot change the backend

Example fix

# before
structured_outputs_config = {"backend": "outlines", "disable_any_whitespace": True}
# after
structured_outputs_config = {"backend": "xgrammar", "disable_any_whitespace": True}

Defensive patterns

Strategy: validation

Validate before calling

cfg = {"backend": "outlines", "disable_any_whitespace": True}
assert not cfg.get("disable_any_whitespace") or cfg.get("backend") in ("xgrammar", "guidance"), \
    "disable_any_whitespace needs xgrammar or guidance"

Type guard

def whitespace_flag_ok(cfg: dict) -> bool:
    return not cfg.get("disable_any_whitespace") or cfg.get("backend") in ("xgrammar", "guidance")

Prevention

Pair whitespace-strictness flags with an explicit backend, never auto-resolve
Maintain a per-backend feature matrix for structured-output options in your config library

When it happens

Trigger: Setting --structured-outputs-config '{"disable_any_whitespace": true, "backend": "outlines"}' (or leaving backend to auto-resolve to an unsupported engine), or setting disable_any_whitespace=True in StructuredOutputsConfig while the effective backend is not xgrammar/guidance.

Common situations: Tightening JSON schema conformance (no whitespace in numbers/strings) for strict downstream parsers and assuming all grammar backends support it; switching backend for performance while keeping the whitespace flag; new flag adopted from docs without checking backend compatibility matrix.

Related errors

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/a99e44b9911925f3. Report an issue: GitHub.