ReplicaAlreadyExistsException

TL;DR — A Region que você está adicionando já está no grupo de replicação da global table. A adição não é idempotente, então uma reexecução da mesma requisição (retry, deploy reproduzido, IaC desviada) falha uma vez que a primeira teve sucesso. Descreva a tabela primeiro e crie apenas réplicas que não estão lá — ou trate esta exceção como "já feito" e siga em frente.

O que significa

ReplicaAlreadyExistsException: The specified replica is already part of
the global table.

O gerenciamento de réplicas é uma mudança de control-plane com uma pré-condição rígida: Create exige que a Region esteja ausente, Delete exige que esteja presente. Pedir para criar eu-west-1 quando eu-west-1 já replica a tabela viola essa pré-condição — o estado que você queria já existe.

Por que acontece

Um passo de provisionamento repetido ou reproduzido — a primeira tentativa teve sucesso (talvez depois de um timeout esconder o sucesso), e o retry readiciona a mesma Region.
Desvio de infrastructure-as-code — a réplica foi adicionada manualmente no console, e então o pipeline de IaC tenta adicioná-la novamente.
Dois caminhos de automação competindo — deploys paralelos ou jobs de expansão de region ambos submetendo a mesma criação de réplica.

Como corrigir

Verifique o grupo de replicação antes de mutá-lo:

aws dynamodb describe-table --table-name orders \
  --query 'Table.Replicas[].RegionName'

Torne a operação idempotente — capture esta exceção na criação (e ReplicaNotFoundException na exclusão) e trate-a como sucesso; a tabela já está no estado desejado:
```
catch (e) {
  if (e.name === 'ReplicaAlreadyExistsException') return; // desired state reached
  throw e;
}
```
Reconcilie a IaC com a realidade — importe a réplica adicionada manualmente para sua stack em vez de deixar todo deploy retentar a criação.
Serialize as mudanças de réplica — uma atualização de réplica por vez por tabela; espere a tabela voltar a ACTIVE (e a nova réplica sair de CREATING) antes da próxima mudança.

Confirmar que uma réplica de fato serve dados — não apenas que a API a aceitou — é uma tarefa de olhar-a-tabela: o app desktop DynoTable navega pela réplica de cada Region diretamente, e a calculadora de preços do DynamoDB mostra o custo contínuo que a Region extra adiciona.

Erros relacionados

ReplicaNotFoundException — a imagem espelhada: excluir uma Region que não está no grupo.
GlobalTableNotFoundException — confusão de API legada-vs-atual.
ResourceInUseException — a tabela está em meio a uma modificação.
Aprenda: DynamoDB global tables

Referências

Verificado pela última vez em 2026-07-13 contra a documentação oficial da AWS vinculada acima.