vllm-project/vllm · error · ValueError

disable_additional_properties is only supported for the…

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.

Solutions

Set backend='guidance' in the structured outputs config
Disable the flag and instead declare additionalProperties: false explicitly inside each JSON schema you pass to guided_json
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}

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Prevention

Put additionalProperties:false inside the request schema (guided_json) instead of relying on a global flag when backend varies
Pin backend explicitly whenever backend-conditional flags are set

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

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

Appendix: 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)