ReplicaAlreadyExistsException

TL;DR — 추가하려는 리전이 이미 글로벌 테이블의 복제 그룹에 있습니다. 추가는 멱등성이 아니므로 첫 번째 요청이 성공하면 동일한 요청(재시도, 재생된 배포, 드리프트된 IaC)의 재실행이 실패합니다. 먼저 테이블을 설명하고 존재하지 않는 복제본만 생성하거나 이 예외를 "이미 완료"로 처리하고 계속 진행하세요.

무엇을 의미하는가

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

복제본 관리는 엄격한 전제 조건이 있는 제어 영역 변경입니다. Create는 리전이 없어야 하고, Delete는 리전이 있어야 합니다. eu-west-1가 이미 테이블을 복제한 상태에서 eu-west-1를 생성하도록 요청하는 것은 해당 전제 조건을 위반하는 것입니다. 즉, 원하는 상태가 이미 존재합니다.

왜 발생하는가

재시도 또는 재생된 프로비저닝 단계 — 첫 번째 시도가 성공했으며(시간 초과로 인해 성공이 숨겨졌을 수도 있음) 재시도를 통해 동일한 리전이 다시 추가됩니다.
코드형 인프라 드리프트 - 복제본이 콘솔에서 수동으로 추가된 후 IaC 파이프라인이 이를 다시 추가하려고 시도합니다.
두 가지 자동화 경로 경주 — 병렬 배포 또는 지역 확장 작업 모두 동일한 복제본 생성을 제출합니다.

어떻게 해결하는가

변이하기 전에 복제 그룹을 확인하세요.

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

작업을 멱등적으로 만듭니다 — 생성 시 이 예외를 포착하고(삭제 시 ReplicaNotFoundException) 이를 성공으로 처리합니다. 테이블이 이미 원하는 상태에 있습니다.
```
catch (e) {
  if (e.name === 'ReplicaAlreadyExistsException') return; // desired state reached
  throw e;
}
```
IaC를 현실과 조화 — 배포할 때마다 생성을 다시 시도하는 대신 수동으로 추가된 복제본을 스택으로 가져옵니다.
복제본 변경 사항 직렬화 — 테이블당 한 번에 하나의 복제본 업데이트; 다음 변경 전에 테이블이 ACTIVE로 돌아가고 새 복제본이 CREATING을 떠날 때까지 기다립니다.
생성을 시도할 때마다 지역을 기록합니다. IaC가 재생될 때 예외는 이미 존재하는 지역의 이름을 지정합니다. 해당 복제본을 다시 생성하는 대신 상태로 가져옵니다.

DynoTable에서 확인

복제본 생성이 성공한 후에는 API가 이를 수락했는지뿐만 아니라 데이터를 제공하는지 확인하세요. ⌘P가 있는 복제본 지역으로 전환하고, ⌘K이 있는 테이블을 열고 항목을 찾아보세요. DynoTable은 각 지역의 사본을 나란히 표시하므로 자동 부분 실패가 분명합니다.

다른 지역을 추가하기 전에 pricing calculator을 사용하여 진행 중인 복제 쓰기 비용을 추정하세요. 설정 → 프로필에서 지역별로 프로필을 구성하고 각각에 대해 연결 테스트를 실행하세요. Connect to AWS 및 Install를 참조하세요. IaC 재생이 원하는 상태에 도달하면 ReplicaAlreadyExistsException를 성공으로 처리합니다. 즉, 리전이 이미 복제 중입니다.

출처

UpdateGlobalTable — Amazon DynamoDB API Reference (2026-07-13 인증)
Global tables — Amazon DynamoDB Developer Guide (2026-07-13 인증)

참고 자료

위에 링크된 공식 AWS 문서를 기준으로 2026년 7월 13일에 마지막으로 확인되었습니다.