How to Fix Azure AI Search: Setup, Indexing & Config Errors

Getting the service creation right from the start saves you from a cascade of downstream problems. Here's exactly how to do it.

In the Azure portal, click Create a resource, search for "Azure AI Search," and select it from the results. On the creation form, pay close attention to these fields:

Subscription and Resource Group: If you're in an organization with multiple subscriptions, confirm you're deploying to the right one. Search services cannot be moved between subscriptions after creation.

Service name: This becomes part of your endpoint URL (https://yourservicename.search.windows.net). Pick something meaningful, you can't rename it later.

Region: This is where people get burned. If you plan to use agentic retrieval (the LLM-assisted multi-query pipeline), you must choose a supported region right now. At the time of writing, agentic retrieval is in public preview with region restrictions. If you pick the wrong region and later try to enable agentic retrieval, you'll need to create a new service entirely. Classic search has no regional restrictions beyond normal Azure data residency requirements.

Pricing tier: The Free tier is fine for development but limits you to 50 MB of storage and 3 indexes. For anything production-bound, start at Basic or Standard S1. The Free tier also restricts you to one instance per subscription, if you already have one somewhere in your Azure account (perhaps from a tutorial months ago), service creation will fail with an error about tier limits.

After creation, enable the system-assigned managed identity immediately: go to Settings > Identity and toggle the status to On. Save. Then go assign that identity the appropriate roles on your data sources before doing anything else. You'll thank yourself later.

# Create a search service using Azure CLI
az search service create \
  --name mysearchservice \
  --resource-group myResourceGroup \
  --sku standard \
  --location eastus \
  --identity-type SystemAssigned

If the command succeeds, you'll see the service provisioning state change to Succeeded within a few minutes. If it fails with QuotaExceeded, you've hit the per-subscription limit for that tier in that region.

This is the decision that most guides gloss over, and it's the one that causes the most rework. Let me give you the real-world breakdown.

Classic search is an index-first model. You define a schema, push or pull data into the index, and then your app sends a query and gets back ranked results in a single request-response cycle. No LLM is involved in the retrieval itself. It's predictable, low-latency, and cost-efficient. If you're building a product catalog search, a document search portal, or a support ticket lookup, classic search is what you want. It supports full-text, vector, hybrid, and multimodal queries. It's generally available and production-stable.

Agentic retrieval is built for a different scenario entirely. Instead of a single index, you define a knowledge base that can point at one or more knowledge sources. When a query comes in, an LLM assists with query planning, breaks the request into focused subqueries, runs them in parallel against the knowledge sources, reranks results semantically, and merges everything into a three-part response optimized for agent consumption. This is the right choice when you're grounding a chatbot or AI agent in proprietary enterprise data and you need it to handle complex, ambiguous, multi-part questions.

Here's the practical decision guide I use:

• Building a search bar on a website or app? → Classic search.
• Adding retrieval to an agent or chatbot? → Agentic retrieval, but only if your region supports it.
• Want multi-source retrieval without full LLM planning overhead? → Agentic retrieval with minimal reasoning effort setting.
• Need real-time data freshness (live content, not indexed snapshots)? → Agentic retrieval with remote knowledge sources, which bypass indexing and query live.

You can use both modes on the same search service, they share the underlying indexing and query engines. Agentic retrieval builds on top of classic search by adding the knowledge base context layer.

To set up a knowledge base for agentic retrieval in the portal, navigate to your search service, click Knowledge bases in the left menu (if you don't see it, your region doesn't support it yet), and click + Create. You'll define knowledge sources and optionally connect an Azure OpenAI or Microsoft Foundry model for LLM-assisted planning.

Indexing errors are the most common class of Azure AI Search problems I see. The indexer pulls data from your source, transforms it, and loads it into the search index. Each stage can fail independently.

Azure AI Search only indexes JSON documents. If your data source isn't natively JSON, the indexer serializes it, but that serialization can fail if the schema is unexpected. For supported data sources (Azure Blob Storage, Azure Cosmos DB, Azure SQL Database, SharePoint, OneLake), use the pull method: let the indexer handle serialization. For custom data or real-time sync requirements, you need the push method and must format your documents as JSON yourself before calling the indexer API.

Diagnosing a failed indexer run:

# Check indexer status via REST API
GET https://[servicename].search.windows.net/indexers/[indexername]/status?api-version=2024-07-01
api-key: [your-admin-key]

The response includes an executionHistory array. Look at the most recent entry. The errors and warnings arrays inside each execution are where your answers are. Common error codes you'll see:

• ExtractionFailure, The indexer couldn't read or parse a document. Check file formats and encoding.
• SkillExecutionError, An AI enrichment skill (chunking, embedding, OCR) failed. Check skill configuration and connected resource quotas.
• MappingError, A field mapping between your data source and index schema is broken. A field in the source doesn't exist in the index schema or types don't match.
• TransientFailure, A temporary issue. Rerun the indexer once. If it fails again consistently, it's not transient.

To reset and manually rerun an indexer from the portal: go to Indexers, select yours, click Reset, then click Run. Alternatively via CLI:

az search indexer reset --name myindexer --service-name mysearchservice --resource-group myResourceGroup
az search indexer run --name myindexer --service-name mysearchservice --resource-group myResourceGroup

After the run completes, check Execution history again. A successful run shows documents processed count greater than zero, with zero errors. If you see documents skipped with no errors, your filter conditions or change detection policy may be excluding content.

Vector search is where I see the most subtle, hard-to-debug problems. The symptom is always the same: similarity search returns results that look completely unrelated. The cause is almost always a mismatch between how you generated embeddings at indexing time versus query time.

Here's the ironclad rule: use the same embedding model, the same vector dimensions, and the same normalization settings for both document ingestion and query vectorization. If you indexed documents using text-embedding-ada-002 (1,536 dimensions) and you're querying with text-embedding-3-small (also 1,536 dimensions by default but a completely different model), your results will be meaningless. The cosine similarity between embeddings from different models has no semantic meaning.

When configuring a vector index in the Azure portal, go to your search service, click Indexes, select your index, and click the Vector profiles tab. Confirm the algorithm configuration (HNSW or exhaustive KNN) and the dimensions match your embedding model. Any mismatch here and your vector queries silently return low-confidence results without throwing an error.

For AI enrichment, chunking, embedding generation, OCR on images, you define a skillset that runs during indexing. Common skillset errors:

# Check skillset execution errors in indexer status
GET https://[servicename].search.windows.net/indexers/[indexername]/status?api-version=2024-07-01

Look for SkillExecutionError in the errors array. This usually means one of:

• The Azure OpenAI resource you connected for embeddings has hit its token-per-minute quota. Go to that resource and check its metrics.
• The skill configuration references a deployment name that doesn't exist or was renamed.
• The chunking skill is producing chunks too large for the embedding model's context window (token limit exceeded).

For hybrid search (combining full-text and vector results), Azure AI Search handles the result fusion internally using Reciprocal Rank Fusion (RRF). You don't need to merge results yourself. Just make sure your index has both a searchable text field and a vector field, then issue a hybrid query that specifies both a search text parameter and a vectorQueries array.

Once data is in the index, the next set of problems is around querying. Let's go through the main ones.

HTTP 403 Forbidden: You're either using a query key for an operation that requires admin access, or your RBAC role assignments are wrong. In the portal go to your search service > Settings > Keys and verify which key you're using. If your app uses Microsoft Entra-based authentication (recommended for production), the calling identity needs either the Search Index Data Reader role (for queries) or Search Index Data Contributor (for write operations) at minimum. Assign these under Access Control (IAM) on the search service resource.

HTTP 429 Too Many Requests: You've exceeded your service's query capacity. Each search unit (SU) has throughput limits. Standard S1 starts at one replica, which handles approximately 15 queries per second (QPS). Scale up replicas to increase query throughput: go to Settings > Scale and add replicas. You can also add partitions to increase storage and indexing throughput.

Relevance tuning: If search results are returning in the wrong order, relevant documents buried below irrelevant ones, you have several tools. The Scoring profiles feature lets you boost certain fields (e.g., title matches count more than body matches). Go to your index definition, click Scoring profiles, and add field weights. For semantic reranking, enable the Semantic ranker on your index and add a queryType=semantic parameter to your queries. The semantic ranker uses Microsoft's language models to reorder results by meaning rather than just keyword frequency.

# Semantic search query example (REST)
POST https://[servicename].search.windows.net/indexes/[indexname]/docs/search?api-version=2024-07-01
Content-Type: application/json
api-key: [your-query-key]

{
  "search": "how to reset password",
  "queryType": "semantic",
  "semanticConfiguration": "my-semantic-config",
  "top": 5
}

If semantic ranker isn't available, confirm your service tier supports it. The Free tier does not include semantic ranking. It's available from Basic tier upward, but you need to enable it in the portal under Settings > Semantic ranker. After enabling, it may take a few minutes to propagate. If the query returns 400 Bad Request with a message about semantic configuration not found, you haven't created the semantic configuration inside your index definition yet, go to the index > Semantic configurations tab and create one.