Attempting to modify a GSI that is being created
TL;DR — 当一个全局二级索引正在构建时(IndexStatus = CREATING),DynamoDB 会拒绝相互冲突的结构性变更。在初始的资源分配阶段,你不能修改新索引、更改索引或表的预置吞吐量、添加或删除其他索引,也不能删除表。一旦回填开始,你可以删除正在进行中的索引,或再次更改表/GSI 的吞吐量,但添加或删除其他索引以及删除表在它变为 ACTIVE 之前仍被阻止。逐个进行 GSI 变更——每次 UpdateTable 只做一个创建或删除。
含义
ValidationException: Attempting to modify a GSI that is being created在一张已有数据的表上创建一个 GSI 会触发一次回填——DynamoDB 在后台把现有项目重放进新索引。在这个阶段,索引的 IndexStatus 为 CREATING。在回填期间,DynamoDB 会拒绝对索引或表进一步的结构性变更,以保持构建的一致性。它是一个 HTTP 400 ValidationException;在索引完成之前,立即重试都会失败。
为什么会发生
- 重叠的索引操作——一个
UpdateTable(或一次 IaC apply)试图在第一个索引仍在构建时修改/删除某个 GSI,或添加第二个。 - CloudFormation/Terraform 批处理——工具试图在单次更新中进行多个 GSI 变更;DynamoDB 每次
UpdateTable只允许一个 GSI 创建或删除。 - 资源分配期间的吞吐量变更——当新索引仍在分配资源时(
Backfilling: false),你不能修改该索引或表的预置吞吐量;一旦回填开始,这些变更就再次被允许。 - 过早删除表——一次与回填竞速的拆除操作。
如何修复
- 等待
ACTIVE。 轮询DescribeTable并检查每个GlobalSecondaryIndexes[].IndexStatus;只有在它为ACTIVE时才继续。索引描述还带有一个aws dynamodb describe-table --table-name <Table> \ --query "Table.GlobalSecondaryIndexes[].{Name:IndexName,Status:IndexStatus}"Backfilling布尔值(false = 资源分配,true = 回填中),而OnlineIndexPercentageProgressCloudWatch 指标可跟踪构建进度。 - 对索引变更排序——每次
UpdateTable一个创建/删除;不要在另一个索引正在构建时添加新的 GSI。 - 在 CloudFormation/Terraform 中,把 GSI 的添加分散到不同的部署中,使每次回填在下一次变更之前完成。
- 推迟其他索引变更和表删除,直到索引变为
ACTIVE。需要中途退出?一旦回填已经开始,你可以通过删除正在创建的索引来取消构建。
在 DynoTable 中重试之前
当 GSI 为 CREATING 时,请在 DynoTable 中打开表并在表详细信息下观察索引状态,然后再对另一个 UpdateTable 进行排队。当你浏览时,应用程序会刷新 DescribeTable — 当 IndexStatus 翻转到 ACTIVE 时,索引会出现在查询模式选择器中,你可以从可视模式或 query builder 中对其进行 Query 操作。当 DynoTable 仍显示 CREATING 时,请勿将 CloudFormation/Terraform GSI 更改堆叠在一项应用中。顺序部署;使用 DynoTable 作为应用之间的真实状态面板。如果你需要在回填开始后取消构建,请从 IaC/CLI 中删除该索引,然后确认它从 DynoTable 索引列表中消失。
来源
- Managing Global Secondary Indexes(2026-07-13 验证)
- UpdateTable — Amazon DynamoDB API Reference(2026-07-13 验证)
相关错误
- Local secondary indexes must be specified at table creation——LSI 的等价情况(LSI 根本无法添加)。
- ResourceInUseException——对一个不处于可修改状态的表/索引进行操作。
- Requested resource not found / index not found——查询一个尚未就绪或不存在的索引。
- 学习:GSI vs LSI · GSI internals
参考资料
- Managing Global Secondary Indexes in DynamoDB — Amazon DynamoDB Developer Guide
- UpdateTable — Amazon DynamoDB API Reference
- Error handling with DynamoDB — Amazon DynamoDB Developer Guide
最后核实于 2026-07-13,依据上方链接的 AWS 官方文档。