sgl-project/sglang · error · ValueError

Cannot parse schema {json_schema}. The schema must be either

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

convert_json_schema_to_str accepts only a Pydantic BaseModel subclass, a dict, or a JSON-schema string; anything else (e.g. a random object, a type that isn't BaseModel, a list) raises ValueError.

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)

Solutions

1. Convert the schema to a dict or JSON string before passing
2. 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

from pydantic import BaseModel
ok = isinstance(json_schema, (str, dict)) or (isinstance(json_schema, type) and issubclass(json_schema, BaseModel))

def is_valid_schema(s):
    from pydantic import BaseModel
    return isinstance(s, (str, dict)) or (isinstance(s, type) and issubclass(s, BaseModel))

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

• schema_ is required for json_schema response format request.
• Kimi K3 additional parameter schema accepts no values
• Kimi K3 tool parameters 'properties' must be an object
• Kimi K3 tool parameters 'required' must be a string list
• Kimi K3 required parameters are missing schemas: {sorted(mis

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/9272c36aa234c421. Report an issue: GitHub.