sgl-project/sglang · error · ValueError
Cannot parse schema . The schema must be either a Pydantic…
Error message
Cannot parse schema {json_schema}. The schema must be either a Pydantic class, a dictionary or a string that contains the JSON schema specification What it means
SGLang client utility error: the given json_schema argument is not a Pydantic model class, dict, or JSON-schema string — the three accepted forms for specifying structured output schemas. Convert the schema to one of these forms (e.g. via YourModel.model_json_schema()).
Solutions
- Convert the schema to a dict or JSON string before passing
- Use a Pydantic BaseModel subclass for structured output schemas
Example fix
# before params.json_schema = MyTypedDict # after params.json_schema = json.dumps(MyAnnotatedSchema) # or use a pydantic BaseModel
Defensive patterns
Strategy: type-guard
Validate before calling
from pydantic import BaseModel ok = isinstance(json_schema, (str, dict)) or (isinstance(json_schema, type) and issubclass(json_schema, BaseModel))
Type guard
def is_valid_schema(s):
from pydantic import BaseModel
return isinstance(s, (str, dict)) or (isinstance(s, type) and issubclass(s, BaseModel)) Prevention
- Use Pydantic models or JSON strings for json_schema
- Validate schema input before building sampling params
When it happens
Trigger: Passing json_schema as a non-string/non-dict/non-BaseModel value to sampling params (e.g. a TypedDict, dataclass, or None) via to_sampling_params / structured output helpers.
Common situations: Using response_format/json_schema with a dataclass or TypedDict instead of Pydantic; passing a schema loaded as a list of schemas.
Understand the failure class
Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.
Related errors
- Kimi K3 additional parameter schema accepts no values
- Kimi K3 required parameter
- Kimi K3 required parameters are missing schemas
- Kimi K3 strict tool must define parameters
- Kimi K3 tool parameters 'additionalProperties' must be a…
AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28).
Data as JSON: /api/errors/9272c36aa234c421.
Report an issue: GitHub.
Appendix: source
Thrown at python/sglang/utils.py:112
json_schema
The JSON schema.
Returns
-------
str
The JSON schema converted to a string.
Raises
------
ValueError
If the schema is not a dictionary, a string or a Pydantic class.
"""
if isinstance(json_schema, dict):
schema_str = json.dumps(json_schema)
elif isinstance(json_schema, str):
schema_str = json_schema
elif issubclass(json_schema, BaseModel):
schema_str = json.dumps(json_schema.model_json_schema())
else:
raise ValueError(
f"Cannot parse schema {json_schema}. The schema must be either "
+ "a Pydantic class, a dictionary or a string that contains the JSON "
+ "schema specification"
)
return schema_str
def get_exception_traceback():
etype, value, tb = sys.exc_info()
err_str = "".join(traceback.format_exception(etype, value, tb))
return err_str
def is_same_type(values: list):
"""Return whether the elements in values are of the same type."""
if len(values) <= 1:
return True
else:View on GitHub (pinned to 0132848349)