Skip to content
⚠️ Before You Start
Risk: Medium
Duration: 1-3 hours plus reprocessing time
Last Validated: Not yet validated (draft)
Kind: Runbook
Risk Note: Medium (a careless reset reprocesses everything and runs up cost)

Recover from indexer and skillset failures and throttling

Draft outline: not validated

Drafted with AI from official sources on 16 Oct 2026. Do not use on a live system until it is written, dry-run by someone other than the author and signed off (planned 2026-11-04). Author: Kranthi · dry-run: Kandiah Chockalingam · sign-off: Yogeshwaran. Work items: RAG-05-T05, RAG-05-T06, RAG-05-T07, RAG-05-T08.

1. Summary

When a scheduled indexer run fails, stalls, reports item errors, or skills hit throttling. Also use it when users report that new documents are not searchable.

Risk: Medium (a careless reset reprocesses everything and runs up cost). Typical duration: 1-3 hours plus reprocessing time.

2. When to use and when not to

Use it when: When a scheduled indexer run fails, stalls, reports item errors, or skills hit throttling. Also use it when users report that new documents are not searchable.

Do not use it when: to be written by the author.

3. What you must know first

  • A run without reset processes only new or changed items from the high-water mark
  • A reset clears the high-water mark and reprocesses everything; it cannot be undone
  • Reset documents and reset skills are preview operations for targeted reprocessing
  • Only one run of an indexer can be in progress at a time
  • Multitenant indexer runs have a maximum duration; long jobs resume on the next scheduled run if change detection is on

4. Prerequisites and access

  • Search Service Contributor role or equivalent to manage indexers
  • Access to indexer execution history and diagnostic logs
  • Knowledge of whether an enrichment cache is enabled
  • Cost owner informed before any full reset

5. Steps

Outline of the steps; the author adds the commands and a check after each one.

  1. Read indexer status and the last execution result with errors and warnings
  2. Classify the failure: data source access, document parsing, skill error, throttling or timeout
  3. Fix the cause, for example credentials, firewall, skill quota or file limits
  4. For a few failed documents, use reset documents (preview) or touch the source files
  5. For a skill change, use reset skills (preview) if the cache is enabled, otherwise plan a reset
  6. For a full reprocess, get cost approval, then reset and run
  7. Run the indexer and watch status until success
  8. Verify counts and spot-check that the failed documents are now searchable
  9. Record root cause and the fix in the operations log

Draft snippet: Check status, then run or reset an indexer

### Status and last execution errors
GET ${SEARCH_ENDPOINT}/indexers/${INDEXER_NAME}/status?api-version=2026-04-01
Authorization: Bearer ${TOKEN}

### Run from the high-water mark (no reset)
POST ${SEARCH_ENDPOINT}/indexers/${INDEXER_NAME}/run?api-version=2026-04-01
Authorization: Bearer ${TOKEN}

### Reprocess named documents only (preview)
POST ${SEARCH_ENDPOINT}/indexers/${INDEXER_NAME}/resetdocs?api-version=2026-05-01-preview
Authorization: Bearer ${TOKEN}
Content-Type: application/json

{ "documentKeys": ["${DOC_KEY_1}", "${DOC_KEY_2}"], "overwrite": true }

Snippets to add:

  • snippets/indexer-ops.http: Status, reset and run calls (http)
  • snippets/indexer_errors.py: Summarise indexer errors by type (python)

6. Monitoring and alerts

Signal Alert when Action
DocumentsProcessedCount with Failed dimension Any failed items in a scheduled run Start this runbook
SkillExecutionCount with Failed dimension Failures above 1% of executions Check skill dependencies and quota
Indexer last successful run Older than two schedule intervals Check status and start this runbook

7. Rollback

To be written by the author: how to undo each risky step.

8. Known issues and fixes

Symptom Likely cause Fix
Run shows 0/0 documents processed No changes since the high-water mark Expected; reset only if a full reprocess is needed
Run fails at once with access errors Data source credentials or network rules changed Fix the managed identity role or firewall and rerun
Skill errors with 429 Embedding or Foundry resource throttled Raise quota or reduce batch size and rerun
Run stops before finishing large corpora Maximum run duration reached Enable change detection and a frequent schedule so runs resume
Start run returns an error Another run is already in progress Wait for it to finish
Credentials provided in the connection string are invalid or have expired Key rotated or expired, managed identity missing roles, or shared key access disabled Update the connection or switch to managed identity with the right role assignments.

9. AWS and open-source equivalents

On Bedrock Knowledge Bases, check ingestion job statistics and failure reasons and start a new sync job. On OpenSearch Ingestion or custom pipelines, use dead-letter queues and replay.

10. Validation record

Pending. Planned dry-run scenario: A second engineer breaks a sandbox indexer by removing its storage role and adding a corrupt file. Pass if both faults are diagnosed from status output, fixed, and the corpus is complete again without a full reset.

11. Sources