microsoft/semantic-kernel · error · ServiceInvalidExecutionSettingsError

response_format must be a dictionary, a subclass of BaseMode

Error message

response_format must be a dictionary, a subclass of BaseModel, a Python class/type, or None

What it means

Raised by the Azure AI Inference settings validator when response_format is not None, not a dict, and not a type/class. The validator accepts a dict (json_object/json_schema), a BaseModel subclass, any plain Python class/type (used as a schema source), or None; any other runtime object (instance, int, list, string) is rejected because it cannot be mapped to a response format.

Source

Thrown at python/semantic_kernel/connectors/ai/azure_ai_inference/azure_ai_inference_prompt_execution_settings.py:82

        if isinstance(response_format, dict):
            if response_format.get("type") == "json_object":
                return values
            if response_format.get("type") == "json_schema":
                json_schema = response_format.get("json_schema")
                if isinstance(json_schema, dict):
                    values["structured_json_response"] = True
                    return values
                raise ServiceInvalidExecutionSettingsError(
                    "If response_format has type 'json_schema', 'json_schema' must be a valid dictionary."
                )
        if isinstance(response_format, type):
            if issubclass(response_format, BaseModel):
                values["structured_json_response"] = True
            else:
                values["structured_json_response"] = True
        else:
            raise ServiceInvalidExecutionSettingsError(
                "response_format must be a dictionary, a subclass of BaseModel, a Python class/type, or None"
            )

        return values


@experimental
class AzureAIInferenceEmbeddingPromptExecutionSettings(PromptExecutionSettings):
    """Azure AI Inference Embedding Prompt Execution Settings.

    Note:
        `extra_parameters` is a dictionary to pass additional model-specific parameters to the model.
    """

    dimensions: Annotated[int | None, Field(gt=0)] = None
    encoding_format: Literal["base64", "binary", "float", "int8", "ubinary", "uint8"] | None = None
    input_type: Literal["text", "query", "document"] | None = None
    extra_parameters: dict[str, str] | None = None

View on GitHub (pinned to c028a0c7dc)

Solutions

Pass the class/type (e.g. MyModel) not an instance (MyModel()).
If you have a dict, use the {'type':'json_schema', ...} or {'type':'json_object'} shapes.
If passing None is acceptable for your call, omit response_format entirely.

Example fix

# before
settings.response_format = MyModel()  # instance → error

# after
settings.response_format = MyModel  # class → accepted

Defensive patterns

Strategy: type-guard

Validate before calling

from typing import Any
from pydantic import BaseModel

def coerce_response_format(rf: Any):
    if rf is None or isinstance(rf, dict):
        return rf
    if isinstance(rf, type) and issubclass(rf, BaseModel):
        return rf
    if isinstance(rf, type):
        return rf
    raise TypeError("response_format must be None, a dict, a BaseModel subclass, or a class/type")

settings.response_format = coerce_response_format(candidate)

Type guard

from pydantic import BaseModel
from typing import Any

def is_acceptable_response_format(rf: Any) -> bool:
    if rf is None:
        return True
    if isinstance(rf, dict):
        return True
    if isinstance(rf, type) and (issubclass(rf, BaseModel) or True):
        return True
    return False

Try / catch

from semantic_kernel.exceptions import ServiceInvalidExecutionSettingsError
try:
    settings.response_format = candidate
except ServiceInvalidExecutionSettingsError:
    settings.response_format = MyModel  # fall back to the class

Prevention

Pass the class, not an instance.
Validate response_format type before assignment.
Use None or a dict/class — never a string or instance.

When it happens

Trigger: Passing an instance of a model instead of the class (e.g. MyModel() instead of MyModel); passing a JSON string; passing a list, int, or other non-type object as response_format.

Common situations: Instantiating a schema model and passing the instance rather than the class; passing a serialized schema string; copy-paste from examples that used a different library's expected type.

Related errors

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/aedd10f3a0656f4f. Report an issue: GitHub.