microsoft/semantic-kernel · error · AgentInitializationException

Missing or malformed 'vector_store_ids' in: {spec}

Error message

Missing or malformed 'vector_store_ids' in: {spec}

What it means

Raised when building a file_search tool and spec.options.vector_store_ids is absent, not a list, or has a falsy first element. The tool requires at least one pre-provisioned Azure vector store ID.

Source

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

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

    return BingGroundingTool(connection_id=conn_id, market=market, set_lang=set_lang, count=count, freshness=freshness)


@_register_tool("code_interpreter")
def _code_interpreter(spec: ToolSpec) -> CodeInterpreterTool:
    file_ids = spec.options.get("file_ids")
    return CodeInterpreterTool(file_ids=file_ids) if file_ids else CodeInterpreterTool()


@_register_tool("file_search")
def _file_search(spec: ToolSpec) -> FileSearchTool:
    vector_store_ids = spec.options.get("vector_store_ids")
    if not vector_store_ids or not isinstance(vector_store_ids, list) or not vector_store_ids[0]:
        raise AgentInitializationException(f"Missing or malformed 'vector_store_ids' in: {spec}")
    return FileSearchTool(vector_store_ids=vector_store_ids)


@_register_tool("function")
def _function(spec: ToolSpec, kernel: "Kernel") -> ToolDefinition:
    def parse_fqn(fqn: str) -> tuple[str, str]:
        parts = fqn.split(".")
        if len(parts) != 2:
            raise AgentInitializationException(f"Function `{fqn}` must be in the form `pluginName.functionName`.")
        return parts[0], parts[1]

    if not spec.id:
        raise AgentInitializationException("Function ID is required for function tools.")
    plugin_name, function_name = parse_fqn(spec.id)
    funcs = kernel.get_list_of_function_metadata_filters({"included_functions": f"{plugin_name}-{function_name}"})

    match len(funcs):
        case 0:

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Create the vector store in Azure AI (via portal or SDK) and add its ID to vector_store_ids as a list.
2. Ensure the value is a list with a non-empty first element.
3. If files must be indexed, upload and create a vector store referencing them, then pass the store ID.

Example fix

// before
tools:
  - type: file_search
    options:
      file_ids: ["file-abc"]

// after
tools:
  - type: file_search
    options:
      vector_store_ids:
        - "vstore-123"

def validate_vector_store_ids(opts: dict) -> None:
    v = opts.get("vector_store_ids")
    if not isinstance(v, list) or not v or not v[0]:
        raise ValueError("file_search requires non-empty list 'vector_store_ids'")

def has_vector_store_ids(opts: dict) -> bool:
    v = opts.get("vector_store_ids")
    return isinstance(v, list) and bool(v) and bool(v[0])

When it happens

Trigger: Declarative spec omits vector_store_ids, provides it as a scalar instead of a list, or passes an empty list for a file_search tool.

Common situations: Developer references a file or blob instead of a vector store ID; forgets to create the vector store first; copies a template placeholder.

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

• Missing or malformed 'tool_connections' in: {spec}
• Missing or malformed 'index_name' in: {spec}
• Function ID is required for function tools.
• OpenAPI tool requires a non-empty 'id' (used as name).
• OpenAPI tool '{spec.id}' requires a 'description'.

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