What causes "Missing or malformed 'index_name' in: {spec}" in microsoft/semantic-kernel?

Add index_name as a non-empty string matching an existing index in the referenced Azure AI Search service.

microsoft/semantic-kernel · error · AgentInitializationException

Missing or malformed 'index_name' in: {spec}

Error message

Missing or malformed 'index_name' in: {spec}

What it means

Raised when an azure_ai_search tool spec has a missing, non-string, or empty index_name. The index name identifies the Azure AI Search index the tool queries.

Source

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

    def decorator(fn: Callable[[ToolSpec, Kernel | None], ToolDefinition]):
        _TOOL_BUILDERS[tool_type.lower()] = fn
        return fn

    return decorator


@_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,

View on GitHub (pinned to c028a0c7dc)

Solutions

Add index_name as a non-empty string matching an existing index in the referenced Azure AI Search service.
If the name is templated, ensure the source variable is set and non-empty before spec construction.
Verify the index exists in the search service linked by the connection ID.

Example fix

// before
options:
  tool_connections:
    - "/.../mySearchConn"

// after
options:
  tool_connections:
    - "/.../mySearchConn"
  index_name: "documents-index"

Defensive patterns

Strategy: validation

Validate before calling

def validate_index_name(opts: dict) -> None:
    name = opts.get("index_name")
    if not isinstance(name, str) or not name:
        raise ValueError("azure_ai_search requires non-empty string 'index_name'")

Type guard

def has_valid_index_name(opts: dict) -> bool:
    n = opts.get("index_name")
    return isinstance(n, str) and bool(n)

Prevention

Use a typed config object (Pydantic/dataclass) for the spec so missing fields fail at parse time.
Assert index_name is non-empty after env-variable substitution.

When it happens

Trigger: Declarative spec omits index_name or sets it to a non-string value (e.g. a number or null) for an azure_ai_search tool.

Common situations: Developer provides the connection ID but forgets the index name; index_name templated from an unset environment variable resolves to empty.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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