How to fix ReplicaAlreadyExistsException: Replica already exists in the global table in DynamoDB

DynamoDBINTERMEDIATEMEDIUMUpdated Dec 22, 2025· 111 views

This error occurs when you attempt to add a replica to a DynamoDB global table in a region where one already exists. Each global table can only have one replica per AWS region. Resolve this by checking existing replicas or removing orphaned ones before recreating.

Quick fix

Fixes ReplicaAlreadyExistsException: Replica already exists in the global table

aws dynamodb describe-global-table \
  --global-table-name your-table-name \
  --region us-east-1
  1. List all existing global tables and their replicas
  2. Check for orphaned replica tables
  3. Delete orphaned replica tables if necessary
  4. Verify the target region does not have an existing replica
dynamodb — error
aws dynamodb describe-global-table \
  --global-table-name your-table-name \
  --region us-east-1
ReplicaAlreadyExistsException: Replica already exists in the global table

What this error means

The ReplicaAlreadyExistsException indicates that the specified replica is already part of the global table. DynamoDB enforces a constraint that each global table can have only one replica table per AWS region. When you attempt to create or add a replica in a region that already has an active replica for the specified global table, DynamoDB rejects the operation to prevent conflicts and data duplication. This error commonly occurs when working with the CreateGlobalTable or UpdateGlobalTable APIs, or when trying to convert an existing table into a global table without properly checking for existing replicas.

Typical symptoms

  • CreateGlobalTable API calls fail immediately with ReplicaAlreadyExistsException
  • UpdateGlobalTable returns an error when attempting to add a new replica
  • Infrastructure-as-code deployments (Terraform, CloudFormation, CDK) fail when creating global table replicas
  • Cross-region replication setup fails unexpectedly

Common causes

  1. Attempting to add a replica in a region that already has an active replica for the global table
  2. Orphaned replica tables from previous deletions remain in the target region
  3. Replica tables exist but are not properly tracked as part of the global table
  4. Concurrent operations trying to add replicas to the same region simultaneously
  5. Using legacy CreateGlobalTable API (version 2017.11.29) with improper region management

How to fix "ReplicaAlreadyExistsException: Replica already exists in the global table"

1List all existing global tables and their replicas

Use the AWS CLI to see which regions already have replicas for your table:

bash
aws dynamodb describe-global-table \
  --global-table-name your-table-name \
  --region us-east-1

Look at the ReplicationGroup output to see all active replicas. Each region should appear only once.

2Check for orphaned replica tables

If you deleted a global table previously, its replicas might persist as standalone tables in other regions. Check each region:

bash
aws dynamodb list-tables --region eu-west-1
aws dynamodb list-tables --region ap-southeast-1
# Check all regions where you intended to have replicas

If you find orphaned tables with the same name as your global table, they need to be deleted before recreating the global table.

3Delete orphaned replica tables if necessary

If you found orphaned replica tables from a previous global table setup, delete them:

bash
aws dynamodb delete-table \
  --table-name your-table-name \
  --region eu-west-1

aws dynamodb delete-table \
  --table-name your-table-name \
  --region ap-southeast-1

Wait for all orphaned tables to be completely deleted before proceeding (this can take a few seconds).

4Verify the target region does not have an existing replica

Before adding a new replica, confirm the target region is not already in the global table:

bash
aws dynamodb describe-global-table \
  --global-table-name your-table-name \
  --region us-east-1 | grep -A 5 ReplicationGroup

If the region you want to add is already listed, you do not need to add it again.

5Add the replica using UpdateGlobalTable (recommended)

Use separate API calls for better reliability. First update to add a new replica:

bash
aws dynamodb update-global-table \
  --global-table-name your-table-name \
  --replica-updates '[
    {
      "Create": {
        "RegionName": "eu-west-1"
      }
    }
  ]' \
  --region us-east-1

AWS recommends issuing separate requests for adding or removing replicas instead of combining both operations in a single call.

6For Global Tables v2 (2019.11.21), use UpdateTable instead

If you are using the current version of global tables (2019.11.21), the UpdateTable API provides a simpler approach:

bash
aws dynamodb update-table \
  --table-name your-table-name \
  --stream-specification StreamEnabled=true,StreamViewType=NEW_AND_OLD_IMAGES \
  --region us-east-1

Then add replicas to the table definition. This is more flexible and consumes less write capacity than the legacy API.

Advanced notes

Global Table Versions: DynamoDB has two versions of global tables. Version 2019.11.21 (Current) is recommended for new tables as it provides greater flexibility, higher efficiency, and consumes less write capacity than version 2017.11.29 (Legacy). If you are still using the legacy version, consider upgrading.

Replica Requirements: When adding a replica to a global table, each replica table must be empty, have the same primary key schema as other replicas, have DynamoDB Streams enabled with both new and old item images, and have the same provisioned write capacity units.

Quota Limits: Each AWS account has quotas for the number of global table replicas per region. If you encounter quota limit errors while adding replicas, create a case in the AWS Support Center to request an increase. The limit cannot be increased through the Service Quotas console.

Concurrent Operations: Do not attempt to add or remove replicas while another replication operation is in progress. Wait for the previous operation to complete fully before issuing the next UpdateGlobalTable command.

Frequently asked questions

What does "ReplicaAlreadyExistsException: Replica already exists in the global ta" mean?
The ReplicaAlreadyExistsException indicates that the specified replica is already part of the global table. DynamoDB enforces a constraint that each global table can have only one replica table per AWS region. When you attempt to create or add a replica in a region that already has an active replica for the specified global table, DynamoDB rejects the operation to prevent conflicts and data duplication.
How do I fix "ReplicaAlreadyExistsException: Replica already exists in the global ta"?
This error occurs when you attempt to add a replica to a DynamoDB global table in a region where one already exists. Each global table can only have one replica per AWS region. Resolve this by checking existing replicas or removing orphaned ones before recreating.
What causes "ReplicaAlreadyExistsException: Replica already exists in the global ta"?
Attempting to add a replica in a region that already has an active replica for the global table Orphaned replica tables from previous deletions remain in the target region Replica tables exist but are not properly tracked as part of the global table
Is the "ReplicaAlreadyExistsException: Replica already exists in the global ta" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading