Advanced8 min read

Why a DynamoDB GSI throttles base-table writes

You write to your table. The write fails with a throughput exception, but the exception names a Global Secondary Index, not the table. The table has spare capacity.

Coming from SQL, that's nonsense: a secondary index can't block an INSERT. In DynamoDB it can, and the mechanism is called GSI back-pressure.

Why does a DynamoDB GSI throttle base-table writes?

A base-table write also writes to every GSI whose keys or projected attributes it changes. If a GSI can't absorb its share, DynamoDB throttles the base-table write so the index doesn't fall behind.

So an under-provisioned GSI, or a low-cardinality GSI key, becomes a hard ceiling on your base-table write rate.

  • An even base table doesn't save you. The GSI is partitioned by its own key. A low-cardinality GSI key (like status) creates a even when base-table writes are perfectly spread.
  • The exception names the GSI; the write it rejected was yours. Read the throttling reason to tell which GSI limit you hit.
  • Fix it with GSI capacity or a GSI key that spreads. Retries alone just queue more writes against the same limit.

How a single write touches the index

A PutItem on the base table can be several writes. DynamoDB replicates the item's projected attributes into each affected GSI asynchronously, on an eventually consistent model.

A GSI is affected when the write sets, changes or removes its key attributes, or changes an attribute it projects. A write that touches neither costs that GSI nothing, and an item that isn't in a sparse index never reaches it.

Each affected GSI must keep up, or the index drifts further from the table on every operation. To stop that drift, DynamoDB applies back-pressure: it throttles the source write.

So the GSI's write capacity is a hard ceiling on your base-table write rate, even though you never write to the GSI directly.

A worked example: a support tickets table

Say you run a support tickets table. The base item:

fieldvaluenote
PK"ACCOUNT#8841"partition key
SK"TICKET#2026-06-23#A7"sort key
ticket_state"PENDING"
queue"billing-eu"
priority2

Base-table writes are healthy. ACCOUNT#... has high cardinality, so ticket writes spread evenly across base partitions. No hot key, plenty of capacity.

Now you add a GSI to answer "show me every ticket in a given state":

GSI: tickets-by-state
fieldvaluenote
GSI-PKticket_state"OPEN" | "PENDING" | "SOLVED" | "CLOSED"
GSI-SKSK

Four possible partition-key values. During an outage, almost every new ticket lands in ticket_state = "OPEN". Every one of those writes hits the same GSI partition.

That partition has a per-partition throughput limit, and you've just aimed your entire write storm at it.

The base table is fine. The OPEN GSI partition is over its limit, so DynamoDB throttles the base-table PutItem to protect the index.

Push more traffic onto the hot key below to watch a low-cardinality index key funnel writes into one partition until it breaches the 1,000 write-unit ceiling:

Partition load and throttling
500 RCU/s
1,800 WCU/s
50 %

The skewed share of all traffic lands on the single hot key USER#1000, which hashes to partition #2; the rest spreads evenly over 24 keys.

Hottest partition: #2 with 62.5% of the traffic — 1 of 4 partitions over a per-partition ceiling.

PartitionKeysTrafficReads (RCU/s)Writes (WCU/s)Status
#0612.5%63225OK
#1612.5%63225OK
#2662.5%3131,125Writes throttled
#3612.5%63225OK

Per-partition ceilings: 3,000 read units/s and 1,000 write units/s — a single physical partition never serves more, regardless of what the table has provisioned.

This is a simplified teaching hash, not DynamoDB’s real internal hash. DynamoDB uses an undocumented internal function and a partition count that grows with your table — use this only to build intuition for how distinct keys spread and a single hot key piles up.

The flow that bites you

Back-pressure path: the base write is balanced, the index write is concentrated.

PutItemticket_state=OPENBase tablespread by ACCOUNT#Async replicateto GSIGSI partitionOPEN (hot)Partition limitexceededThrottle theBASE write

A hot GSI partition rejects the base-table write that fed it.

Read the throttling reason code

The exception's ResourceArn names the GSI, and its throttling reason tells you which limit ran out. The throttled operation is still your table write.

ModeExceptionReason codeWhat ran out
ProvisionedProvisionedThroughputExceededExceptionIndexWriteProvisionedThroughputExceededGSI's provisioned write capacity
BothThrottlingExceptionIndexWriteKeyRangeThroughputExceededA single hot GSI partition
On-demandThrottlingExceptionIndexWriteMaxOnDemandThroughputExceededGSI's configured max on-demand throughput
On-demandThrottlingExceptionIndexWriteAccountLimitExceededThe table-level throughput quota for that GSI (default 40,000 write request units per second)

Source: Understanding GSI write throttling and back pressure.

The KeyRange reason is the giveaway for the hot-partition case above: overall GSI capacity can look fine while one key range is saturated.

How to fix it

Give the GSI room. A GSI has its own read and write capacity, separate from the table (see GSI vs LSI). AWS recommends provisioning a GSI's write capacity at least equal to the table's.

Raise it in place with UpdateTable. On a provisioned table:

aws dynamodb update-table --table-name Tickets \
  --global-secondary-index-updates '[{"Update":{"IndexName":"tickets-by-state",
    "ProvisionedThroughput":{"ReadCapacityUnits":100,"WriteCapacityUnits":2000}}}]'

On on-demand, send "OnDemandThroughput":{"MaxWriteRequestUnits":N} in the same Update block instead. For a spike you can see coming (a launch, a planned migration), set the GSI's WarmThroughput there ahead of time, which raises the write rate it can take immediately.

For IndexWriteAccountLimitExceeded, request a higher table-level write throughput quota in the Service Quotas console; the 40,000 default is adjustable.

Fix the partition key. Raising capacity doesn't lift a single partition's ceiling of about 1,000 write units per second, so a low-cardinality key needs a redesign.

Folding the date in (OPEN#2026-06-23) only spreads load across days: a one-day outage still lands on one key.

Write-shard it instead: append a suffix 0 to N-1 (say, the ticket id hashed mod N) to the state, and read the state back with N parallel Query calls merged on SK. Hot partitions covers write sharding and finding hot keys with CloudWatch Contributor Insights.

Since November 2025 a GSI key can span up to four partition-key attributes, so ticket_state and a numeric shard can be two typed key attributes instead of a concatenated OPEN#3 string. Each query still names one shard.

Project fewer attributes. Each GSI write copies the projected attributes. A KEYS_ONLY or tight INCLUDE projection means smaller index writes, and updates to attributes the GSI doesn't store cost it nothing.

Drop the GSI if it's only for reporting. If "tickets by state" is an occasional admin question, not a hot path, a periodic scan with a filter may beat a permanently hot index. Weigh it against Query vs Scan.

When you do query that index, the key condition looks like this. The Expression Builder generates an equivalent one, with its own placeholder names and the values typed for you:

KeyConditionExpression     "#s = :state AND begins_with(SK, :prefix)"
ExpressionAttributeNames   { "#s": "ticket_state" }
ExpressionAttributeValues  { ":state": { "S": "OPEN" }, ":prefix": { "S": "TICKET#2026-06-23" } }

The trap to remember

The relational instinct ("indexes only slow writes a little") does not transfer. A GSI's write capacity caps your table's write rate. Under-size it or pick a clumping key, and it back-pressures the table it serves.

Watch the per-reason throttle metrics on the GSI (dimensions TableName and GlobalSecondaryIndexName): WriteKeyRangeThroughputThrottleEvents, WriteProvisionedThroughputThrottleEvents and WriteMaxOnDemandThroughputThrottleEvents.

Alongside them, track ConsumedWriteCapacityUnits and WriteThrottleEvents on the same dimensions, and WriteAccountLimitThrottleEvents on the table.

Guides that prevent the next GSI throttle

  • GSI vs LSI: why a GSI has its own capacity and a different partition key.
  • Hot partitions: finding the hot key and sharding it.
  • Single-table design: overloading one GSI to serve many patterns without multiplying hot indexes.
  • Query vs Scan: when an index isn't worth its write cost.

Try DynoTable to inspect every GSI on your tables (key schema, projection and size) and query your indexes before a launch.

By Dmitriy · Updated