DynamoDB ReplicaNotFoundException

TL;DR — The region replica you're trying to update or remove isn't part of this global table. Usually a wrong region name, a replica that was already removed, or a call that races another in-flight replica update. Confirm the current replicas with DescribeTable, then target one that exists.

What it means

ReplicaNotFoundException: The specified replica <region> was not found

Global-tables operations (UpdateGlobalTable, or UpdateTable with a ReplicaUpdates/Delete) address a replica by its AWS region. This HTTP 400 means the region you named isn't currently a replica of the global table. It's client-side and not retryable until you target a real replica.

Why it happens

• Wrong region code — us-east-2 when the replica is in us-east-1, or a region that was never added.
• Replica already removed — a delete against a region that a previous update already dropped from the table.
• Concurrent replica change — global tables allow one replica add/remove per update; a second overlapping call sees inconsistent membership.
• Confusing the primary with a replica — operating on a region that hosts no replica of this table.
• Version confusion — mixing the legacy Version 2017.11.29 (GlobalTable) and current 2019.11.21 (replica-on-table) APIs.

How to fix it

1. List the current replicas and their status:

   aws dynamodb describe-table --table-name <Table> \
     --query "Table.Replicas[].{Region:RegionName,Status:ReplicaStatus}"

2. Target a region that's actually in the list — copy the region code exactly.
3. Change one replica at a time. Wait for the previous add/remove to reach ACTIVE before the next update.
4. Removing a replica that's already gone? There's nothing to do — treat the ReplicaNotFoundException as already-satisfied for a delete.
5. Use the current (2019.11.21) API — manage replicas via UpdateTable ReplicaUpdates, not the legacy global-table API.

Managing tables across regions? The DynoTable desktop app shows each table's replicas and their status, so you can act on a region that's genuinely part of the global table.

Related errors

• ResourceNotFoundException — the table itself isn't found in the region/account.
• ResourceInUseException — a replica change conflicts with the table's current state.
• Learn: Global tables