요약: Terraform의 "Error acquiring the state lock"은 다른 실행이 state lock을 잡고 있거나, 비정상 종료로 lock이 해제되지 않아 발생합니다. 먼저 Lock Info로 실행 중인 작업이 없는지 확인한 뒤 -lock-timeout으로 대기하고, 실행 주체가 종료된 경우에만 terraform force-unlock LOCK_ID로 해제하세요.
🔍 검색 키워드: 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를 쓰게 되어 복구하기 어려운 손상이 생길 수 있습니다.
자주 묻는 질문(FAQ)
terraform force-unlock을 써도 안전한가요?
실행 중인 plan/apply가 없다는 것을 확인한 뒤에만 안전합니다. lock은 state 동시 수정을 막는 장치이므로, 작업이 살아 있는 상태에서 강제로 풀면 두 실행이 동시에 state를 써서 손상될 수 있습니다. Lock Info의 Who, Created 값과 CI 로그로 먼저 확인하세요.
Error acquiring the state lock이 계속 반복되는 이유는 무엇인가요?
CI에서 같은 state를 쓰는 job이 동시에 실행되거나, job이 취소·타임아웃되어 unlock이 실행되지 못하는 경우가 대부분입니다. concurrency 그룹으로 apply를 직렬화하고 -lock-timeout을 지정해 두면 재발을 줄일 수 있습니다.
-lock=false 옵션을 사용해도 되나요?
lock을 아예 잡지 않는 옵션이라 동시 실행 시 state가 손상될 위험이 있어 권장하지 않습니다. 읽기 전용 plan처럼 영향이 없음을 확실히 아는 경우에만 제한적으로 고려하세요.
force-unlock에 필요한 Lock ID는 어디서 확인하나요?
에러 메시지의 Lock Info 블록에 있는 ID 값입니다. 터미널 출력이 사라졌다면 DynamoDB lock 테이블 항목의 Info 필드에서도 확인할 수 있습니다.
참고 문서: terraform force-unlock · State Locking
최종 업데이트: 2026-10-01 · 작성: 내멋스레 사는 이야기
댓글 없음:
댓글 쓰기