microsoft/autogen · error · ValueError

vector_fields must contain at least one field name for vecto

Error message

vector_fields must contain at least one field name for vector search

What it means

For the vector search factory, _validate_config requires config_dict['vector_fields'] to be a non-empty list — the client-side embedding is matched to the index's vector field by this name, so vector search cannot be constructed without it.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/tools/azure/_ai_search.py:636

    def _validate_config(
        cls, config_dict: Dict[str, Any], search_type: Literal["full_text", "vector", "hybrid"]
    ) -> None:
        """Validate configuration for specific search types."""
        credential = config_dict.get("credential")
        if isinstance(credential, str):
            raise TypeError("Credential must be AzureKeyCredential, AsyncTokenCredential, or a valid dict")
        if isinstance(credential, dict) and "api_key" not in credential:
            raise ValueError("If credential is a dict, it must contain an 'api_key' key")

        try:
            _ = AzureAISearchConfig(**config_dict)
        except Exception as e:
            raise ValueError(f"Invalid configuration: {str(e)}") from e

        if search_type == "vector":
            vector_fields = config_dict.get("vector_fields")
            if not vector_fields or len(vector_fields) == 0:
                raise ValueError("vector_fields must contain at least one field name for vector search")

        elif search_type == "hybrid":
            vector_fields = config_dict.get("vector_fields")
            search_fields = config_dict.get("search_fields")

            if not vector_fields or len(vector_fields) == 0:
                raise ValueError("vector_fields must contain at least one field name for hybrid search")

            if not search_fields or len(search_fields) == 0:
                raise ValueError("search_fields must contain at least one field name for hybrid search")

    @classmethod
    @abstractmethod
    def _from_config(cls, config: AzureAISearchConfig) -> "BaseAzureAISearchTool":
        """Create a tool instance from a configuration object.

        This is an abstract method that must be implemented by subclasses.
        """

View on GitHub (pinned to 027ecf0a37)

Solutions

Pass the exact vector field name defined in the index: vector_fields=['content_vector'].
Check the index definition (Fields section in the portal or az search index show) for the field of type Collection(Edm.Single) marked as a vector field.
For hybrid search remember search_fields is also required in addition to vector_fields.

Example fix

# before
tool = await AzureAISearchTool.create_vector_search_tool(name='v', endpoint=ep, index_name='idx', credential=cred, embedding_provider='openai', embedding_model='text-embedding-ada-002', openai_api_key=k)
# after
tool = await AzureAISearchTool.create_vector_search_tool(name='v', endpoint=ep, index_name='idx', credential=cred, vector_fields=['content_vector'], embedding_provider='openai', embedding_model='text-embedding-ada-002', openai_api_key=k)

Defensive patterns

Strategy: validation

Validate before calling

def vector_config_ready(config_dict: dict) -> bool:
    vf = config_dict.get('vector_fields')
    return isinstance(vf, list) and len(vf) > 0 and all(isinstance(f, str) and f for f in vf)

Type guard

def has_vector_fields(vector_fields) -> bool:
    return isinstance(vector_fields, (list, tuple)) and len(vector_fields) > 0

Prevention

Keep vector_fields next to query_type='vector' in one config block so they change together.
Record the index's vector field name in the same place you define the ingestion pipeline that writes it.
Assert vector_fields non-empty in config tests.

When it happens

Trigger: Calling the vector factory (e.g. AzureAISearchTool.for_vector_search or the vector constructor around line 933's config) without vector_fields, with vector_fields=None, or with vector_fields=[].

Common situations: Copy-pasting the full-text constructor example and switching query_type to 'vector' without adding vector_fields; assuming the tool auto-detects the vector field; index renamed its vector column (content_vector vs embedding).

Related errors

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/dd8316fdca6901bd. Report an issue: GitHub.