microsoft/semantic-kernel · error · AgentInitializationException

Invalid query_type '{raw_query_type}' in: {spec}

Error message

Invalid query_type '{raw_query_type}' in: {spec}

What it means

Raised when an azure_ai_search tool spec's query_type string does not map to any AzureAISearchQueryType enum member (after lowercasing). Valid members are typically simple, full, semantic, vector, vector_simple_hybrid, vector_semantic_hybrid.

Source

Thrown at python/semantic_kernel/agents/azure_ai/azure_ai_agent.py:117

@_register_tool("azure_ai_search")
def _azure_ai_search(spec: ToolSpec) -> AzureAISearchTool:
    opts = spec.options or {}

    connections = opts.get("tool_connections")
    if not connections or not isinstance(connections, list) or not connections[0]:
        raise AgentInitializationException(f"Missing or malformed 'tool_connections' in: {spec}")
    conn_id = connections[0]

    index_name = opts.get("index_name")
    if not index_name or not isinstance(index_name, str):
        raise AgentInitializationException(f"Missing or malformed 'index_name' in: {spec}")

    raw_query_type = opts.get("query_type", AzureAISearchQueryType.SIMPLE)
    if type(raw_query_type) is str:
        try:
            query_type = AzureAISearchQueryType(raw_query_type.lower())
        except ValueError:
            raise AgentInitializationException(f"Invalid query_type '{raw_query_type}' in: {spec}")
    else:
        query_type = raw_query_type

    filter_expr = opts.get("filter", "")

    top_k = opts.get("top_k", 5)
    if not isinstance(top_k, int):
        raise AgentInitializationException(f"'top_k' must be an integer in: {spec}")

    return AzureAISearchTool(
        index_connection_id=conn_id,
        index_name=index_name,
        query_type=query_type,
        filter=filter_expr,
        top_k=top_k,
    )

View on GitHub (pinned to c028a0c7dc)

Solutions

  1. Set query_type to a valid AzureAISearchQueryType member string: simple, full, semantic, vector, vector_simple_hybrid, or vector_semantic_hybrid.
  2. Omit query_type to accept the default (SIMPLE) when a basic search is acceptable.
  3. Inspect AzureAISearchQueryType.__members__ in your installed version for the authoritative list.

Example fix

// before
options:
  query_type: hybrid

// after
options:
  query_type: vector_simple_hybrid
# or omit for default SIMPLE
Defensive patterns

Strategy: validation

Validate before calling

from semantic_kernel.connectors.ai.azure_ai.azure_ai_search_query_type import AzureAISearchQueryType

def validate_query_type(raw):
    if isinstance(raw, str) and raw.lower() not in {m.value for m in AzureAISearchQueryType}:
        raise ValueError(f"query_type '{raw}' is invalid")
    return raw

Type guard

def is_valid_query_type(raw) -> bool:
    if not isinstance(raw, str):
        return True
    return raw.lower() in {m.value for m in AzureAISearchQueryType}

Prevention

When it happens

Trigger: Setting query_type to an unrecognized string (e.g. 'hybrid', 'keyword', 'fuzzy') in the declarative spec; passing a value valid for the REST API but not the SDK enum.

Common situations: Developer guesses a query type name; version skew between the enum members the installed SDK knows and the Azure docs being followed.

Related errors

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