Sửa lỗi Terraform 'Inconsistent dependency lock file' Sau Khi Thêm hoặc Cập Nhật Provider

Lỗi Gặp Phải

Bạn chạy terraform plan hoặc terraform apply và bị dừng lại đột ngột:

Error: Inconsistent dependency lock file

The following dependency selections recorded in the lock file are inconsistent with the current configuration:
  - provider registry.terraform.io/hashicorp/aws: locked version selection 4.67.0 doesn't match the
    constraint "~> 5.0" recorded in the configuration

To update the locked dependency selections to match a changed configuration, run:
  terraform init -upgrade

Chín trong mười trường hợp, nguyên nhân rất đơn giản: ai đó đã chỉnh sửa required_providers trong versions.tf — nâng version constraint, thêm provider, hoặc bất kỳ thay đổi nào — nhưng không chạy terraform init sau đó.

Nguyên Nhân Gốc Rễ

Terraform duy trì một file .terraform.lock.hcl. Hãy coi nó như một tờ biên lai: các phiên bản provider chính xác kèm theo checksum mật mã, được đóng băng tại thời điểm bạn chạy terraform init lần cuối.

Ngay khi các file .tf của bạn khai báo một constraint mâu thuẫn với các phiên bản đã được ghim đó, Terraform sẽ dừng lại. Nó sẽ không âm thầm chọn một phiên bản khác. Đây là điều có chủ đích — việc thay đổi phiên bản ngầm chính là nguyên nhân khiến môi trường production bị lỗi theo cách rất khó truy vết.

Các nguyên nhân thường gặp:

Cập nhật version constraint trong required_providers (ví dụ: ~> 4.0 → ~> 5.0)
Thêm một provider block mới chưa có trong lock file
Pull code từ git trong đó đồng nghiệp đã thay đổi provider constraints hoặc chính lock file
Xóa thư mục .terraform/ cache nhưng giữ lại lock file cũ
Chạy trên hệ điều hành khác — CI trên Linux/amd64 trong khi dev dùng macOS/arm64 — khiến lock file chỉ có checksum cho một nền tảng

Cách Khắc Phục

Tùy chọn 1: Để Terraform nâng cấp lock file (cách khắc phục phổ biến nhất)

Terraform đã nói thẳng trong output lỗi những gì bạn cần chạy:

terraform init -upgrade

Lệnh này giải quyết lại mọi provider theo constraints hiện tại và viết lại .terraform.lock.hcl từ đầu. Hãy commit ngay lập tức.

git add .terraform.lock.hcl
git commit -m "chore: update terraform provider lock file"

Tùy chọn 2: Thêm provider mới mà không thay đổi các pin hiện có

Vừa thêm một provider hoàn toàn mới và không muốn rủi ro thay đổi các thứ khác? Bỏ qua flag -upgrade:

terraform init

terraform init thông thường chỉ tải về các provider còn thiếu trong lock file. Các phiên bản đã được ghim vẫn giữ nguyên. Lựa chọn an toàn hơn khi thay đổi của bạn chỉ là bổ sung thêm.

Tùy chọn 3: Khắc phục lỗi checksum không khớp giữa các nền tảng

CI pipeline của bạn (Linux/amd64) bị lỗi, nhưng MacBook (macOS/arm64) chạy bình thường. Lock file có checksum cho kiến trúc laptop của bạn nhưng không có cho CI runner. Khắc phục mà không thay đổi bất kỳ phiên bản nào:

terraform providers lock \
  -platform=linux_amd64 \
  -platform=darwin_arm64 \
  -platform=darwin_amd64

Commit kết quả. Lock file giờ đây mang checksum cho mọi nền tảng mà team bạn sử dụng, và CI sẽ ngừng báo lỗi.

Tùy chọn 4: Ghim phiên bản chính xác để ngăn drift

Giả sử -upgrade kéo về provider aws phiên bản 5.89.0 và bạn chưa sẵn sàng cho điều đó. Hãy khóa cứng nó trong versions.tf:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "= 5.31.0"  # ghim chính xác, không drift
    }
  }
}

Chạy lại terraform init -upgrade. Terraform sẽ khóa về 5.31.0 bất kể đồng nghiệp của bạn dùng -upgrade trên máy của họ như thế nào.

Tùy chọn 5: Xóa lock file và bắt đầu lại từ đầu (phương án cuối cùng)

Dành cho trường hợp lock file thực sự bị hỏng hoặc môi trường hoàn toàn mới bạn đang khởi tạo từ đầu:

rm .terraform.lock.hcl
terraform init

Terraform sẽ tạo lại mọi thứ từ đầu. Hãy kiểm tra các pin mới trước khi commit — bạn cần biết mình đang chạy những phiên bản nào.

Xác Nhận Đã Khắc Phục

Hai bước kiểm tra nhanh sau khi áp dụng bất kỳ cách khắc phục nào ở trên:

# Phải hoàn thành mà không có lỗi
terraform init

# Phải hiển thị plan mà không có lỗi lock file
terraform plan

Xác nhận lock file thực sự có phiên bản provider mà bạn mong đợi:

grep -A3 'provider "registry.terraform.io/hashicorp/aws"' .terraform.lock.hcl

Bạn sẽ thấy kết quả tương tự như sau:

provider "registry.terraform.io/hashicorp/aws" {
  version     = "5.31.0"
  constraints = "~> 5.0"
  hashes = [

Phòng Ngừa

Luôn commit .terraform.lock.hcl — không có ngoại lệ. Hãy đối xử với nó giống như package-lock.json. Đây không phải tùy chọn, không phải nhiễu, và không thuộc về .gitignore.
Chạy terraform init sau mỗi lần pull có đụng chạm đến file .tf. Hãy biến nó thành thói quen, đặc biệt sau khi versions.tf thay đổi.
Thêm checksum cho các nền tảng trước commit CI đầu tiên. Chạy terraform providers lock -platform=linux_amd64 trên máy local để CI runner không bao giờ gặp lỗi mismatch ngay từ ngày đầu.
Dùng pin chính xác = x.y.z trong môi trường chia sẻ hoặc production. Range constraints như ~> 5.0 tiện lợi trong development nhưng có thể gây vấn đề khi đồng nghiệp dùng -upgrade và âm thầm kéo về phiên bản minor mới hơn.
Nếu bạn cần kiểm tra cú pháp version constraint trong các khối YAML của versions.tf, YAML ↔ JSON Converter trên ToolCraft rất hữu ích — chạy hoàn toàn trên trình duyệt, không cần upload file.

Tham Khảo Nhanh

# Thêm provider mới → chỉ cần init
terraform init

# Cập nhật version constraint → nâng cấp lock file
terraform init -upgrade

# CI mismatch giữa các nền tảng → thêm platform checksums
terraform providers lock -platform=linux_amd64 -platform=darwin_arm64

# Phương án tối hạn (lock file bị hỏng)
rm .terraform.lock.hcl && terraform init

# Luôn commit lock file sau khi thay đổi
git add .terraform.lock.hcl && git commit -m "chore: update lock file"