microsoft/autogen · error · ValueError

vector_fields must contain at least one field name for hybri

Error message

vector_fields must contain at least one field name for hybrid search

What it means

Same rule as 926 but for the hybrid factory: hybrid search sends both a vector query and full-text terms, so vector_fields must name at least one vector field of the index before the tool can be constructed.

Source

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

        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.
        """
        if cls is BaseAzureAISearchTool:
            raise NotImplementedError(
                "BaseAzureAISearchTool is an abstract base class and cannot be instantiated directly. "
                "Use a concrete implementation like AzureAISearchTool."
            )
        raise NotImplementedError("Subclasses must implement _from_config")

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Pass vector_fields=['<vector-field-name>'] matching the index's Collection(Edm.Single) field.
2. Also pass non-empty search_fields (hybrid requires both — see error 928).
3. Verify both field names against the index schema before constructing the tool.

Example fix

# before
tool = await AzureAISearchTool.create_hybrid_search_tool(name='h', endpoint=ep, index_name='idx', credential=cred, search_fields=['content'])
# after
tool = await AzureAISearchTool.create_hybrid_search_tool(name='h', endpoint=ep, index_name='idx', credential=cred, vector_fields=['content_vector'], search_fields=['content'])

def hybrid_config_ready(config_dict: dict) -> bool:
    vf = config_dict.get('vector_fields')
    sf = config_dict.get('search_fields')
    return bool(vf) and len(vf) > 0 and bool(sf) and len(sf) > 0

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

When it happens

Trigger: Calling the hybrid search factory (constructor near line 1109) with vector_fields omitted, None, or an empty list.

Common situations: Upgrading a full-text tool to hybrid by only changing query_type and adding search_fields, forgetting the vector side; index vector field renamed during a re-ingestion.

Related errors

• vector_fields must contain at least one field name for vecto
• search_fields must contain at least one field name for hybri
• vector_fields must be provided for vector search
• Invalid configuration: {str(e)}
• semantic_config_name is required when query_type is 'semanti

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