microsoft/autogen · error · ValueError

Error from Azure AI Search: {error_msg}

Error message

Error from Azure AI Search: {error_msg}

What it means

The catch-all branch of the tool's error handling: any exception from the Azure AI Search SDK that is neither 'not found' nor 'unauthorized/401' is re-raised as ValueError('Error from Azure AI Search: <original message>'). The original exception is preserved as __cause__, so `except ValueError as e: e.__cause__` still exposes the HttpResponseError details.

Source

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

            if self.search_config.enable_caching:
                self._cache[cache_key] = {"results": results, "timestamp": time.time()}

            return SearchResults(results=results)

        except asyncio.CancelledError:
            raise
        except Exception as e:
            error_msg = str(e)
            if isinstance(e, HttpResponseError):
                if hasattr(e, "message") and e.message:
                    error_msg = e.message

            if "not found" in error_msg.lower():
                raise ValueError(f"Index '{self.search_config.index_name}' not found.") from e
            elif "unauthorized" in error_msg.lower() or "401" in error_msg:
                raise ValueError(f"Authentication failed: {error_msg}") from e
            else:
                raise ValueError(f"Error from Azure AI Search: {error_msg}") from e

    def _to_config(self) -> AzureAISearchConfig:
        """Convert the current instance to a configuration object."""
        return self.search_config

    @property
    def schema(self) -> ToolSchema:
        """Return the schema for the tool."""
        return {
            "name": self.name,
            "description": self.description,
            "parameters": {
                "type": "object",
                "properties": {"query": {"type": "string", "description": "Search query text"}},
                "required": ["query"],
                "additionalProperties": False,
            },
            "strict": True,

View on GitHub (pinned to 027ecf0a37)

Solutions

  1. Inspect the chained cause: except ValueError as e: print(e.__cause__) — the HttpResponseError status code and message identify the real problem.
  2. Fix per status: 400 → validate filter syntax and field names against the index definition; 429 → add retry/backoff or reduce request rate; 5xx → retry with backoff.
  3. Confirm api_version (default DEFAULT_API_VERSION) supports the features you use (semantic, vector) for your service tier.
  4. Test the same query with a minimal standalone SearchClient script to isolate whether the issue is the tool config or the service/index itself.

Example fix

# before
results = await tool.run(args)
# after (surface the underlying SDK error)
try:
    results = await tool.run(args)
except ValueError as e:
    cause = e.__cause__
    status = getattr(cause, 'status_code', None)
    raise RuntimeError(f'Search failed (HTTP {status}): {cause}') from cause
Defensive patterns

Strategy: retry

Type guard

def is_throttling(cause) -> bool:
    return getattr(cause, 'status_code', None) == 429

Try / catch

import asyncio

async def run_search_with_retry(tool, args, attempts=3):
    for i in range(attempts):
        try:
            return await tool.run(args)
        except ValueError as e:
            cause = e.__cause__
            status = getattr(cause, 'status_code', None)
            if status in (429, 500, 503) and i < attempts - 1:
                await asyncio.sleep(2 ** i)
                continue
            raise

Prevention

When it happens

Trigger: Any SDK/runtime failure during the search call: HTTP 400 from a malformed OData filter or invalid search_fields/select_fields (nonexistent field names), HTTP 429 throttling, HTTP 5xx service errors, semantic query against an index without a semantic configuration, wrong api_version, network/DNS failures, or a vector query against a non-vector field.

Common situations: Bad OData filter syntax in hybrid search; select_fields listing fields not in the index; api_version set to a preview version that does not support the used feature; search service throttling under load; semantic ranking requested on a basic tier that does not support it.

Related errors

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