🔍 검색 키워드: Terraform state lock 에러, Error acquiring the state lock 해결, terraform force-unlock 사용법, Terraform S3 DynamoDB lock, Terraform apply 중단 lock 해제, terraform lock ID
증상: terraform plan/apply가 state lock 에러로 멈춘다
팀 단위로 Terraform을 쓰거나 CI에서 apply를 돌리다 보면, 아무 변경도 하지 않았는데 다음과 같은 에러와 함께 명령이 중단되는 경우가 있습니다. 이 에러는 원격 백엔드(S3+DynamoDB, Terraform Cloud 등)에 state lock이 남아 있어서 발생합니다.
Error: Error acquiring the state lock
Error message: ConditionalCheckFailedException: The conditional request failed
Lock Info:
ID: 3f2a9c1e-7b64-1d0e-9a3f-6c1b2d4e5f70
Path: my-bucket/prod/terraform.tfstate
Operation: OperationTypeApply
Who: runner@ci-worker-12
Version: 1.6.6
Created: 2026-09-30 01:12:44 +0000 UTC원인: 다른 실행이 진행 중이거나, 비정상 종료로 lock이 남음
Terraform은 state 파일이 동시에 수정되어 깨지는 것을 막기 위해 plan/apply 전에 lock을 잡고, 끝나면 해제합니다. lock이 남는 대표적인 경우는 다음과 같습니다.
- 정상적인 동시 실행: 다른 팀원이나 CI 파이프라인이 실제로 apply 중인 경우
- 비정상 종료: Ctrl+C 강제 종료, CI job 취소·타임아웃, 네트워크 단절로 unlock이 실행되지 못한 경우
- DynamoDB 잔여 항목: S3 백엔드의 lock 테이블에 이전 실행의 LockID 항목이 그대로 남은 경우
- 병렬 파이프라인 설계 문제: 같은 state를 쓰는 job이 동시에 트리거되도록 구성된 경우
해결방법 1: 먼저 진짜 실행 중인지 확인하기
가장 중요한 단계입니다. 에러 메시지의 Who, Created, Operation을 확인해 지금도 실제로 실행 중인 작업인지 먼저 확인하세요. 실행 중인 apply의 lock을 강제로 풀면 state가 손상될 수 있습니다. 해당 CI job이 이미 종료됐거나 담당자가 중단했음을 확인한 뒤에만 다음 단계로 넘어갑니다.
해결방법 2: 대기 옵션으로 자동 재시도
잠깐 겹친 실행이라면 lock이 풀릴 때까지 기다리게 할 수 있습니다. CI에서는 이 옵션을 기본으로 두는 것이 좋습니다.
terraform plan -lock-timeout=5m
terraform apply -lock-timeout=5m해결방법 3: terraform force-unlock으로 안전하게 해제
실행 주체가 이미 죽었다고 확인됐다면, 에러 메시지에 나온 Lock ID로 강제 해제합니다.
terraform force-unlock 3f2a9c1e-7b64-1d0e-9a3f-6c1b2d4e5f70
Do you really want to force-unlock?
Enter a value: yes
Terraform state has been successfully unlocked!해결방법 4: S3 + DynamoDB 백엔드에서 lock 항목 직접 삭제
force-unlock이 실패하는 경우(권한 문제, 항목 손상 등)에는 lock 테이블의 항목을 직접 확인하고 삭제할 수 있습니다. 이 방법은 최후의 수단이며, 삭제 전에 반드시 항목 내용을 확인하세요.
aws dynamodb get-item --table-name terraform-locks \
--key '{"LockID":{"S":"my-bucket/prod/terraform.tfstate"}}'
aws dynamodb delete-item --table-name terraform-locks \
--key '{"LockID":{"S":"my-bucket/prod/terraform.tfstate"}}'재발 방지: 백엔드 설정과 CI 구성
lock 자체는 문제가 아니라 안전장치입니다. 남는 lock을 줄이려면 백엔드에 lock 테이블을 명시하고, CI에서는 같은 state에 대해 job이 직렬로만 실행되도록 제한합니다.
terraform {
backend "s3" {
bucket = "my-bucket"
key = "prod/terraform.tfstate"
region = "ap-northeast-2"
dynamodb_table = "terraform-locks"
encrypt = true
}
}# GitHub Actions: 같은 state에 대한 apply를 직렬화
concurrency:
group: terraform-prod
cancel-in-progress: false정리표
| 상황 | 확인 방법 | 조치 |
|---|---|---|
| 다른 실행이 진행 중 | Who/Created 확인, CI 로그 | -lock-timeout으로 대기 |
| 비정상 종료로 lock 잔존 | 실행 주체가 종료됐는지 확인 | terraform force-unlock LOCK_ID |
| force-unlock 실패 | DynamoDB 항목 조회 | 항목 확인 후 delete-item |
| 반복 발생 | CI 동시 실행 여부 | concurrency 직렬화, timeout 설정 |
핵심은 lock을 풀기 전에 실행 중인 작업이 없는지 반드시 확인하는 것입니다. 확인 없이 force-unlock을 습관처럼 쓰면 두 실행이 동시에 state를 쓰게 되어 복구하기 어려운 손상이 생길 수 있습니다.
