{"record":{"id":"36d1cda0937fdbe5","repo":"BerriAI/litellm","slug":"unsupported-response-format-type-response-forma","errorCode":null,"errorMessage":"Unsupported response_format type - {response_format}","messagePattern":"Unsupported response_format type - (.+?)","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"litellm/llms/base_llm/base_utils.py","lineNumber":190,"sourceCode":"    response_format: type[BaseModel] | dict | None,\n    ref_template: str | None = None,\n) -> dict | None:\n    \"\"\"\n    Re-implementation of openai's 'type_to_response_format_param' function\n\n    Used for converting pydantic object to api schema.\n    \"\"\"\n    if response_format is None:\n        return None\n\n    if isinstance(response_format, dict):\n        return _dict_to_response_format_helper(response_format, ref_template)\n\n    # type checkers don't narrow the negation of a `TypeGuard` as it isn't\n    # a safe default behaviour but we know that at this point the `response_format`\n    # can only be a `type`\n    if not _parsing._completions.is_basemodel_type(response_format):\n        raise TypeError(f\"Unsupported response_format type - {response_format}\")\n\n    if ref_template is not None:\n        schema = response_format.model_json_schema(ref_template=ref_template)\n    else:\n        schema = _pydantic.to_strict_json_schema(response_format)\n\n    return {\n        \"type\": \"json_schema\",\n        \"json_schema\": {\n            \"schema\": schema,\n            \"name\": response_format.__name__,\n            \"strict\": True,\n        },\n    }\n\n\ndef map_developer_role_to_system_role(\n    messages: list[AllMessageValues],","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/llms/base_llm/base_utils.py#L172-L208","documentation":"When converting a response_format into a JSON schema, LiteLLM accepts either a plain dict or a pydantic BaseModel subclass. Anything else — a class that is not a BaseModel (dataclass, TypedDict, attrs, plain class), or an instance instead of the class — raises TypeError('Unsupported response_format type - ...').","triggerScenarios":"Calling completion(..., response_format=MyDataclass) or response_format=SomePydanticModel(**fields) (an instance); passing a TypedDict class or a string like 'json_object' where a schema type is expected; the OpenAI SDK's pydantic classes from a different pydantic version instance.","commonSituations":"Migrating instructor-style code; mixing pydantic v1/v2 models; passing an enum or Generic alias; assuming OpenAI's response_format={'type':'json_object'} dict shorthand works under a typed API.","solutions":["Make response_format a pydantic BaseModel subclass: class Output(BaseModel): ... ; pass Output, not Output()","Or pass a dict schema directly: response_format={'type':'json_schema','json_schema':{...}}","For dataclasses/TypedDicts, convert first (e.g. pydantic TypeAdapter(...).json_schema()) or redefine them as BaseModel","For plain JSON mode use response_format={'type': 'json_object'} (dict form) rather than a non-pydantic class"],"exampleFix":"# before\nfrom dataclasses import dataclass\n@dataclass\nclass Output:\n    answer: str\nlitellm.completion(model=..., messages=..., response_format=Output)\n\n# after\nfrom pydantic import BaseModel\nclass Output(BaseModel):\n    answer: str\nlitellm.completion(model=..., messages=..., response_format=Output)","handlingStrategy":"type-guard","validationCode":"from pydantic import BaseModel\n\ndef ensure_response_format(rf):\n    if rf is None or isinstance(rf, dict):\n        return rf\n    if isinstance(rf, BaseModel):\n        rf = type(rf)\n    if not (isinstance(rf, type) and issubclass(rf, BaseModel)):\n        raise TypeError(f'response_format must be a BaseModel subclass or dict, got {rf!r}')\n    return rf","typeGuard":"from pydantic import BaseModel\n\ndef is_response_format_valid(rf) -> bool:\n    if rf is None or isinstance(rf, dict):\n        return True\n    if isinstance(rf, BaseModel):\n        return True\n    return isinstance(rf, type) and issubclass(rf, BaseModel)","tryCatchPattern":"try:\n    litellm.completion(model=m, messages=msgs, response_format=Output)\nexcept TypeError as e:\n    if 'Unsupported response_format type' in str(e):\n        # convert dataclass/TypedDict to BaseModel and retry\n        raise\n    raise","preventionTips":["Standardize on pydantic BaseModel subclasses for structured output across the codebase","Pass the class, never an instance, as response_format","Add a lint/test that feeds every schema used with response_format through the guard"],"tags":["response-format","type-error","pydantic","json-schema"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}