{"record":{"id":"4a4a63370917a038","repo":"microsoft/semantic-kernel","slug":"missing-or-malformed-vector-store-ids-in-spec-4a4a63","errorCode":null,"errorMessage":"Missing or malformed 'vector_store_ids' in: {spec}","messagePattern":"Missing or malformed 'vector_store_ids' in: (.+?)","errorType":"exception","errorClass":"AgentInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/open_ai/openai_responses_agent.py","lineNumber":96,"sourceCode":"# region Declarative Spec\n\n_TOOL_BUILDERS: dict[str, Callable[[ToolSpec, Kernel | None], ToolParam]] = {}\n\n\ndef _register_tool(tool_type: str):\n    def decorator(fn: Callable[[ToolSpec, Kernel | None], ToolParam]):\n        _TOOL_BUILDERS[tool_type.lower()] = fn\n        return fn\n\n    return decorator\n\n\n@_register_tool(\"file_search\")\ndef _file_search(spec: ToolSpec, kernel: Kernel | None = None) -> FileSearchToolParam:\n    options = spec.options or {}\n    vector_store_ids = options.get(\"vector_store_ids\")\n    if not vector_store_ids or not isinstance(vector_store_ids, list) or not vector_store_ids[0]:\n        raise AgentInitializationException(f\"Missing or malformed 'vector_store_ids' in: {spec}\")\n\n    filters = options.get(\"filters\")\n    max_num_results = options.get(\"max_num_results\")\n    ranking_options = options.get(\"ranking_options\", {})\n    score_threshold = ranking_options.get(\"score_threshold\")\n    ranker = ranking_options.get(\"ranker\")\n\n    return OpenAIResponsesAgent.configure_file_search_tool(\n        vector_store_ids=vector_store_ids,\n        filters=filters,\n        max_num_results=max_num_results,\n        score_threshold=score_threshold,\n        ranker=ranker,\n    )\n\n\n@_register_tool(\"web_search\")\ndef _web_search(spec: ToolSpec, kernel: Kernel | None = None) -> WebSearchToolParam:","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/open_ai/openai_responses_agent.py#L78-L114","documentation":"Raised by the registered 'file_search' tool builder in openai_responses_agent when a file_search tool spec's options.vector_store_ids is missing, not a list, or an empty/None-first-element list. The Responses file_search tool requires at least one valid vector store id, so the builder validates before calling configure_file_search_tool.","triggerScenarios":"A declarative tool spec of type 'file_search' with options lacking 'vector_store_ids', with it set to None, a single string instead of a list, or a list whose first entry is falsy; building tools from a YAML spec where the field is misnamed.","commonSituations":"YAML tool config missing vector_store_ids; passing a string id where a list is expected; vector store not yet created so the id is empty; key typo (vectorStoreIds vs vector_store_ids).","solutions":["Provide options={'vector_store_ids': ['vs_xxx']} with a non-empty list of valid store ids.","Create the vector store first (client.vector_stores.create) and use the returned id.","Validate spec.options['vector_store_ids'] is a non-empty list of strings before building tools."],"exampleFix":"# before\ntool_spec = {'type':'file_search','options':{'vector_store_ids': None}}\n\n# after\ntool_spec = {'type':'file_search','options':{'vector_store_ids': ['vs_abc123']}}","handlingStrategy":"validation","validationCode":"opts = spec.get('options', {})\nvs = opts.get('vector_store_ids')\nassert isinstance(vs, list) and vs and vs[0], 'vector_store_ids must be a non-empty list'","typeGuard":"def has_valid_vector_store_ids(spec: dict) -> bool:\n    vs = (spec.get('options') or {}).get('vector_store_ids')\n    return isinstance(vs, list) and bool(vs and vs[0])","tryCatchPattern":"from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException\ntry:\n    tool = _build_tool(tool_spec, kernel)\nexcept AgentInitializationException as e:\n    if 'vector_store_ids' in str(e):\n        tool_spec['options']['vector_store_ids'] = [vs_id]\n        tool = _build_tool(tool_spec, kernel)","preventionTips":["Create the vector store before referencing it.","Use snake_case vector_store_ids as a list.","Validate tool options before building."],"tags":["configuration","agents","openai-responses","file-search","vector-store"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}