{"record":{"id":"b38e1231274ac5be","repo":"microsoft/semantic-kernel","slug":"missing-or-malformed-index-name-in-spec","errorCode":null,"errorMessage":"Missing or malformed 'index_name' in: {spec}","messagePattern":"Missing or malformed 'index_name' in: (.+?)","errorType":"validation","errorClass":"AgentInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/azure_ai/azure_ai_agent.py","lineNumber":110,"sourceCode":"    def decorator(fn: Callable[[ToolSpec, Kernel | None], ToolDefinition]):\n        _TOOL_BUILDERS[tool_type.lower()] = fn\n        return fn\n\n    return decorator\n\n\n@_register_tool(\"azure_ai_search\")\ndef _azure_ai_search(spec: ToolSpec) -> AzureAISearchTool:\n    opts = spec.options or {}\n\n    connections = opts.get(\"tool_connections\")\n    if not connections or not isinstance(connections, list) or not connections[0]:\n        raise AgentInitializationException(f\"Missing or malformed 'tool_connections' in: {spec}\")\n    conn_id = connections[0]\n\n    index_name = opts.get(\"index_name\")\n    if not index_name or not isinstance(index_name, str):\n        raise AgentInitializationException(f\"Missing or malformed 'index_name' in: {spec}\")\n\n    raw_query_type = opts.get(\"query_type\", AzureAISearchQueryType.SIMPLE)\n    if type(raw_query_type) is str:\n        try:\n            query_type = AzureAISearchQueryType(raw_query_type.lower())\n        except ValueError:\n            raise AgentInitializationException(f\"Invalid query_type '{raw_query_type}' in: {spec}\")\n    else:\n        query_type = raw_query_type\n\n    filter_expr = opts.get(\"filter\", \"\")\n\n    top_k = opts.get(\"top_k\", 5)\n    if not isinstance(top_k, int):\n        raise AgentInitializationException(f\"'top_k' must be an integer in: {spec}\")\n\n    return AzureAISearchTool(\n        index_connection_id=conn_id,","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/azure_ai/azure_ai_agent.py#L92-L128","documentation":"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.","triggerScenarios":"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.","commonSituations":"Developer provides the connection ID but forgets the index name; index_name templated from an unset environment variable resolves to empty.","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."],"exampleFix":"// before\noptions:\n  tool_connections:\n    - \"/.../mySearchConn\"\n\n// after\noptions:\n  tool_connections:\n    - \"/.../mySearchConn\"\n  index_name: \"documents-index\"","handlingStrategy":"validation","validationCode":"def validate_index_name(opts: dict) -> None:\n    name = opts.get(\"index_name\")\n    if not isinstance(name, str) or not name:\n        raise ValueError(\"azure_ai_search requires non-empty string 'index_name'\")","typeGuard":"def has_valid_index_name(opts: dict) -> bool:\n    n = opts.get(\"index_name\")\n    return isinstance(n, str) and bool(n)","tryCatchPattern":null,"preventionTips":["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."],"tags":["azure-ai-agent","declarative-spec","azure-ai-search","configuration"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}