ReplicaAlreadyExistsException

요약 — 추가하려는 리전이 이미 글로벌 테이블의 복제 그룹에 있습니다. 추가는 멱등하지 않으므로, 첫 번째가 성공한 후 같은 요청을 다시 실행하면(재시도, 재생된 배포, 드리프트된 IaC) 실패합니다. 먼저 테이블을 describe하고 없는 복제본만 생성하거나 — 이 예외를 "이미 완료됨"으로 취급하고 넘어가세요.

무엇을 의미하나요

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

복제본 관리는 하드 전제 조건이 있는 제어 플레인 변경입니다: Create는 리전이 없어야 하고, Delete는 있어야 합니다. eu-west-1이 이미 테이블을 복제하는데 eu-west-1을 생성하도록 요청하는 것은 그 전제 조건을 위반합니다 — 원한 상태가 이미 존재합니다.

왜 발생하나요

재시도되거나 재생된 프로비저닝 단계 — 첫 시도가 성공했는데(타임아웃이 성공을 숨겼을 수 있음) 재시도가 같은 리전을 다시 추가합니다.
Infrastructure-as-code 드리프트 — 복제본이 콘솔에서 수동으로 추가되었는데 IaC 파이프라인이 다시 추가하려고 합니다.
두 자동화 경로 경합 — 병렬 배포나 리전 확장 작업이 둘 다 같은 복제본 생성을 제출합니다.

어떻게 고치나요

변경하기 전에 복제 그룹을 확인하세요:

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

작업을 멱등하게 만드세요 — 생성 시 이 예외를(그리고 삭제 시 ReplicaNotFoundException을) catch하고 성공으로 취급하세요. 테이블은 이미 원하는 상태입니다:
```
catch (e) {
  if (e.name === 'ReplicaAlreadyExistsException') return; // desired state reached
  throw e;
}
```
IaC를 현실과 조정하세요 — 모든 배포가 생성을 다시 시도하게 두는 대신 수동으로 추가한 복제본을 스택에 가져오세요.
복제본 변경을 직렬화하세요 — 테이블당 한 번에 하나의 복제본 업데이트. 다음 변경 전에 테이블이 ACTIVE로 돌아오기를(그리고 새 복제본이 CREATING을 떠나기를) 기다리세요.

복제본이 API가 수락했다는 것만이 아니라 실제로 데이터를 제공하는지 확인하는 것은 테이블을 살펴보는 작업입니다: DynoTable 데스크톱 앱은 각 리전의 복제본을 직접 탐색하고, DynamoDB 요금 계산기는 추가 리전이 더하는 지속 비용을 보여줍니다.

References

공식 AWS 문서(위 링크)를 기준으로 2026-07-13에 마지막으로 검증되었습니다.

ReplicaAlreadyExistsException

무엇을 의미하나요

왜 발생하나요

어떻게 고치나요

관련 오류

References