Troubleshoot by Symptom
| Symptom | First checks | Reference |
|---|---|---|
_start fails with target not found | Confirm the target index exists. | REST API |
_start fails with plugin consistency error | Run _cat/plugins on all nodes. | Install the Plugin |
Migration stays PENDING | Check aosc.backfill.max_concurrent_per_node. | Runbook |
Migration stays BACKFILLING | Check target indexing pressure, bulk rejections, heap, and disk. | Runbook |
Migration stays CONVERGING | Check convergence gap, source write rate, and global checkpoint movement. | Runbook |
| Migration fails during transform | Check shard error and script logs. | Transform Documents |
| Writes fail during cutover | Confirm application retry behavior. | Known Limitations |
| Alias did not move | Check coordinator phase, alias state, and cutover errors. | Monitor |
| Retention leases remain after failure | Confirm migration is terminal, then use cleanup lease dry-run. | Cancel and Clean Up |
_clear_state is needed | Prefer cancellation first; use dry-run before clearing. | REST API |
Useful commands:
bash
curl -s 'http://localhost:9200/_plugins/_aosc/my-index-v1/_status' | jq '.'
curl -s 'http://localhost:9200/_plugins/_aosc/_list' | jq '.'
curl -s 'http://localhost:9200/_cluster/health' | jq '.'
curl -s 'http://localhost:9200/_cat/shards?v'
curl -s 'http://localhost:9200/_cat/plugins?v'