vllm-project/vllm · error · ValueError

disable_additional_properties is only supported for the guid

Error message

disable_additional_properties is only supported for the guidance backend.

What it means

StructuredOutputsConfig requires backend='guidance' when disable_additional_properties=True. Injecting additionalProperties:false into JSON schemas is a transformation performed only by the guidance backend's schema pipeline; xgrammar and the other backends pass the schema through and cannot guarantee the constraint. The validator raises immediately at config construction rather than silently ignoring the flag.

Source

Thrown at vllm/config/structured_outputs.py:70

        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

1. Set backend='guidance' in the structured outputs config
2. Disable the flag and instead declare additionalProperties: false explicitly inside each JSON schema you pass to guided_json
3. Audit request-level schemas and add the constraint in the schema itself if you must keep a non-guidance backend

Example fix

# before
structured_outputs_config = {"backend": "xgrammar", "disable_additional_properties": True}
# after
structured_outputs_config = {"backend": "guidance", "disable_additional_properties": True}

cfg = {"disable_additional_properties": True}
assert not cfg.get("disable_additional_properties") or cfg.get("backend") == "guidance", \
    "disable_additional_properties needs guidance backend"

def addl_props_ok(cfg: dict) -> bool:
    return not cfg.get("disable_additional_properties") or cfg.get("backend") == "guidance"

When it happens

Trigger: Passing disable_additional_properties=True in StructuredOutputsConfig (or the --structured-outputs-config CLI JSON) while backend is unset or set to 'xgrammar'/'outlines'/'lm-format-enforcer'.

Common situations: Hardening JSON schemas so models cannot emit undeclared keys, then discovering only guidance supports the rewrite; copying a guidance-tuned config onto an xgrammar deployment; enabling the flag fleet-wide without per-backend feature checks.

Related errors

• disable_any_whitespace is only supported for xgrammar and gu
• {kind} parsing is not available for model `{model_id}`
• {kind} parsing is disabled by frontend configuration
• {kind} parser `{name}` is not registered{}
• failed to build structural tag: {message}

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