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 官方文件。