"The bot doesn't know about the new policy document" usually means the document never made it into the index.
1. Check the indexer status
az rest --method get \
--url "https://<search>.search.windows.net/indexers/<indexer>/status?api-version=2024-07-01" \
--headers "api-key=<admin-key>" --query "{last:lastResult.status, errors:lastResult.errors[0:5], warnings:lastResult.warnings[0:5], processed:lastResult.itemsProcessed, failed:lastResult.itemsFailed}"
Or in the portal: Indexers → your indexer → Execution history, then open errors and warnings for the document keys.
2. Common errors
| Error / warning | Cause | Fix |
|---|---|---|
Credentials provided in the connection string are invalid or have expired / 403 on the data source | Key rotated, SAS expired, or managed identity lacks a role | Use the search service's managed identity with Storage Blob Data Reader (or the right role for SQL/Cosmos) |
| Can't reach the source; storage firewall | Storage account not public and no trusted access | Allow trusted Microsoft services / resource instance rule, or a shared private link |
Document is too large to be processed / extraction truncated | Blob above the tier's size limit, or text over the extraction limit | Split documents; use a higher tier; set indexedFileNameExtensions to skip unneeded types |
| Could not parse the document / unsupported content type | Encrypted or corrupted PDF, image-only PDF | Exclude, or add OCR via a skillset (imageAction) |
Skill errors: Web Api response status: 429 or timeouts | The embedding or custom skill endpoint is throttled | Raise the model deployment's quota; lower batchSize/degreeOfParallelism; increase the skill timeout |
| Field mapping errors | Source field name or type changed | Update fieldMappings / outputFieldMappings |
3. Make it tolerant (but don't hide failures)
"parameters": {
"maxFailedItems": 10,
"maxFailedItemsPerBatch": 5,
"configuration": { "dataToExtract": "contentAndMetadata", "failOnUnsupportedContentType": false }
}
With -1 for maxFailedItems the indexer never fails the run, so alert on itemsFailed instead, or you'll never notice.
4. Change detection and deletions
- Blob indexers pick up changes by last-modified time. Re-uploading with the same timestamp may not trigger reindexing.
- Deleted files stay in the index unless you configure a deletion detection policy (soft delete with native blob soft delete or a metadata flag).
5. Reset and rerun
POST /indexers/<indexer>/reset?api-version=2024-07-01 (full re-crawl of everything)
POST /indexers/<indexer>/run?api-version=2024-07-01
A full reset re-runs every skill, including embedding calls, for every document. That costs time and money on large sources. For a few documents, use reset documents (resetdocs, preview API) with the keys, or touch the blobs.
6. Monitor
Enable diagnostic settings to Log Analytics and alert when an indexer run's status is not success, or itemsFailed > 0.
Tip
Add a tiny "canary" document to the source with a unique phrase. A scheduled query for that phrase tells you end to end whether new content is reaching the index.