microsoft/autogen · error · ValueError

search_fields must contain at least one field name for hybri

Error message

search_fields must contain at least one field name for hybrid search

What it means

The hybrid factory additionally requires search_fields — the text fields the full-text half of the hybrid query runs against. An empty or missing list fails validation before any config object is built.

Source

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

        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")

    @abstractmethod
    async def _get_embedding(self, query: str) -> List[float]:
        """Generate embedding vector for the query text."""

View on GitHub (pinned to 027ecf0a37)

Solutions

Pass search_fields=['content'] (or the index's searchable text fields).
Confirm the named fields exist and are marked searchable in the index definition.
Keep vector_fields and search_fields together whenever configuring hybrid search.

Example fix

# before
search_fields=[]  # or omitted
# after
search_fields=['content', 'title']

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Prevention

Always set search_fields when configuring hybrid search; do not assume text fields are implicit.
Cross-check field names with the index's searchable attributes.
Cover this rule in config validation tests.

When it happens

Trigger: Calling the hybrid search factory with search_fields omitted, None, or [] while only providing vector_fields.

Common situations: Treating hybrid as 'vector plus semantic ranking' and assuming text fields are implicit; index uses different text field names (body vs content vs text) than the example code.

Related errors

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