{"record":{"id":"958510311f1261ac","repo":"microsoft/semantic-kernel","slug":"response-format-must-be-a-dictionary-a-subclass-o-958510","errorCode":null,"errorMessage":"response_format must be a dictionary, a subclass of BaseModel, a Python class/type, or None","messagePattern":"response_format must be a dictionary, a subclass of BaseModel, a Python class/type, or None","errorType":"validation","errorClass":"ServiceInvalidExecutionSettingsError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/ai/open_ai/prompt_execution_settings/open_ai_prompt_execution_settings.py","lineNumber":143,"sourceCode":"\n        if isinstance(response_format, dict):\n            if response_format.get(\"type\") == \"json_object\":\n                return values\n            if response_format.get(\"type\") == \"json_schema\":\n                json_schema = response_format.get(\"json_schema\")\n                if isinstance(json_schema, dict):\n                    values[\"structured_json_response\"] = True\n                    return values\n                raise ServiceInvalidExecutionSettingsError(\n                    \"If response_format has type 'json_schema', 'json_schema' must be a valid dictionary.\"\n                )\n        if isinstance(response_format, type):\n            if issubclass(response_format, BaseModel):\n                values[\"structured_json_response\"] = True\n            else:\n                values[\"structured_json_response\"] = True\n        else:\n            raise ServiceInvalidExecutionSettingsError(\n                \"response_format must be a dictionary, a subclass of BaseModel, a Python class/type, or None\"\n            )\n\n        return values\n\n\nclass OpenAIEmbeddingPromptExecutionSettings(PromptExecutionSettings):\n    \"\"\"Specific settings for the text embedding endpoint.\"\"\"\n\n    input: str | list[str] | list[int] | list[list[int]] | None = None\n    ai_model_id: Annotated[str | None, Field(serialization_alias=\"model\")] = None\n    encoding_format: Literal[\"float\", \"base64\"] | None = None\n    user: str | None = None\n    extra_headers: dict | None = None\n    extra_query: dict | None = None\n    extra_body: dict | None = None\n    timeout: float | None = None\n    dimensions: Annotated[int | None, Field(gt=0, le=3072)] = None","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/ai/open_ai/prompt_execution_settings/open_ai_prompt_execution_settings.py#L125-L161","documentation":"The response_format field on OpenAIChatPromptExecutionSettings only accepts one of: a dict, a pydantic BaseModel subclass, a plain Python class/type, or None. If none of these isinstance/issubclass checks match (e.g. passing an instance object, a list, a string, or an integer), the validator falls through to the else branch and raises ServiceInvalidExecutionSettingsError.","triggerScenarios":"Passing an already-instantiated BaseModel object (not the class) as response_format; passing a list, tuple, string, or number; passing a JSON string instead of a parsed dict.","commonSituations":"Confusing the class and instance: response_format=MyModel() instead of response_format=MyModel; passing a JSON-encoded string from an API payload without json.loads(); passing a frozenset or other non-type non-dict object.","solutions":["Pass the BaseModel subclass (the type), not an instance: response_format=MyModel, not MyModel().","If passing a string, parse it first: response_format=json.loads(my_string) so it becomes a dict.","Set response_format to None to disable structured output entirely."],"exampleFix":"// before\nsettings.response_format = MyModel()  # instance — fails\n// after\nsettings.response_format = MyModel  # class/type — works","handlingStrategy":"type-guard","validationCode":"from pydantic import BaseModel\n\ndef validate_response_format(response_format) -> None:\n    if response_format is None:\n        return\n    if isinstance(response_format, dict):\n        return\n    if isinstance(response_format, type) and issubclass(response_format, BaseModel):\n        return\n    if isinstance(response_format, type):\n        return\n    raise TypeError(\n        'response_format must be a dict, a BaseModel subclass, a Python type, or None; '\n        f'got {type(response_format).__name__}'\n    )","typeGuard":"from pydantic import BaseModel\n\ndef is_valid_response_format(rf) -> bool:\n    if rf is None:\n        return True\n    if isinstance(rf, dict):\n        return True\n    if isinstance(rf, type) and (issubclass(rf, BaseModel) or True):\n        return True\n    return False","tryCatchPattern":"from semantic_kernel.exceptions import ServiceInvalidExecutionSettingsError\n\ntry:\n    settings = OpenAIChatPromptExecutionSettings(response_format=rf)\nexcept ServiceInvalidExecutionSettingsError as e:\n    if 'must be a dictionary' in str(e):\n        rf = type(rf) if isinstance(rf, BaseModel) else rf  # pass class not instance\n        settings = OpenAIChatPromptExecutionSettings(response_format=rf)","preventionTips":["Pass the BaseModel class (type), never an instance, as response_format.","If deserializing from JSON, parse strings with json.loads before assignment.","Default response_format to None rather than guessing a format."],"tags":["openai","response-format","type-error","execution-settings","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}