适用版本： 6.8-7.9
1. 错误异常的基本描述 #
start array expected [snapshots] 出现在解析快照仓库元数据时。源码明确要求 snapshots 字段当前 token 必须是 START_ARRAY，如果拿到的是对象、字符串或其他结构，就会抛出这条异常。
常见现象 #
- 列快照、读取仓库 metadata 或恢复仓库状态时失败。
- 报错直接点名
snapshots字段。 - 说明 metadata 文件能被读到，但结构已经不符合 Elasticsearch 的预期格式。
典型报错与异常栈 #
ElasticsearchParseException: start array expected [snapshots]
2. 为什么会发生这个错误 #
仓库根元数据中的 snapshots 应该是一个数组，用来保存仓库里的快照记录。如果这个字段被写成对象、字符串，或者 metadata 被截断、损坏，解析器就无法继续。常见原因包括：
- 仓库 metadata 文件被外部程序错误改写。
- 版本迁移或第三方工具生成了不兼容结构。
- 仓库根目录中的 metadata 文件损坏。
- 底层对象存储返回了不完整内容。
3. 如何排查和解决这个异常和解决这个异常 #
- 确认失败发生在列快照、恢复快照还是仓库校验阶段。
- 查看是否同时存在 repository data、snapshot read 等其他 metadata 异常。
- 在允许的前提下检查底层仓库 metadata 文件，确认
snapshots是否真的是数组。 - 对比最近一次可用备份或同类仓库的 metadata 结构。
- 如果 metadata 已损坏且无法修复，考虑从备份或可用仓库重新构建。
排查时需要注意的问题 #
- 这通常不是单个快照不存在，而是仓库元数据结构出错。
- 不要随意手工修改仓库内部文件。
- 如果仓库位于对象存储，还要排查外部程序是否写入了同一路径。
4. 如何解决这个错误 #
常用修复思路 #
- 恢复正确的仓库 metadata 文件，让
snapshots保持数组结构。 - 停止外部工具直接改写 Elasticsearch 仓库目录。
- 对损坏仓库先做只读检查，再决定是否重建。
- 加强仓库目录访问控制，避免被非 Elasticsearch 程序写入。
后续注意事项与推荐建议 #
- 对仓库目录启用严格的变更控制。
- 对对象存储仓库保留 generation 和 metadata 审计信息。
- 新接入第三方工具前，确认其不会改写仓库内部格式。
借助 INFINI 产品提升排障效率 #
- INFINI Console 可帮助观察快照类错误是否集中爆发。
- INFINI Gateway 可审计异常时段的仓库管理请求。
5. 小结 #
start array expected [snapshots] 指向的是快照仓库 metadata 结构损坏或不兼容。处理重点是校验仓库元数据，而不是先看单个业务索引。
相关错误 #
- failed-to-get-snapshots-how-to-solve-this-elasticsearch-exception
- snapshot-could-not-be-read-how-to-solve-this-elasticsearch-exception
- could-not-read-repository-data-from-index-blob-how-to-solve-this-elasticsearch-exception
附：日志上下文 #
parser.nextToken();
if (INDEX_ID.equals(indexMetaFieldName)) {
indexId = new IndexId(indexName, parser.text());
} else if (SNAPSHOTS.equals(indexMetaFieldName)) {
if (parser.currentToken() != XContentParser.Token.START_ARRAY) {
throw new ElasticsearchParseException("start array expected [snapshots]");
}
}
