Fix lỗi Terraform "Error: Failed to query available provider packages" (Provider Not Found)

TL;DR

Terraform không thể kết nối tới provider registry, hoặc không tìm thấy phiên bản phù hợp với constraints của bạn. Hãy bắt đầu với terraform init -upgrade và kiểm tra kết nối mạng. Corporate proxy chặn HTTPS tới registry? Chín trong mười trường hợp, đó chính là vấn đề thực sự. Dùng registry tùy chỉnh hoặc private? Kiểm tra lại địa chỉ source trong required_providers.

Lỗi Đầy Đủ Trông Như Thế Nào

Error: Failed to query available provider packages

│ Could not retrieve the list of available versions for provider
│ hashicorp/aws: could not connect to registry.terraform.io: Failed to
│ request discovery document: Get
│ "https://registry.terraform.io/.well-known/terraform.json": dial tcp:
│ lookup registry.terraform.io: no such host

Hoặc biến thể do version constraint:

Error: Failed to query available provider packages

│ Could not retrieve the list of available versions for provider
│ hashicorp/azurerm: no available releases match the given constraints
│ >= 3.0.0,  3.114

Nguyên Nhân Gốc Rễ

Không có kết nối internet — Terraform không thể kết nối tới registry.terraform.io
Corporate proxy / firewall — Lưu lượng HTTPS tới registry bị chặn
Version constraint không hợp lệ — Block required_providers của bạn có các phiên bản mâu thuẫn hoặc không tồn tại
Địa chỉ source provider sai — Đánh sai tên hoặc còn sót lại cách khai báo provider ngầm định của Terraform 0.12
Lock file cũ — .terraform.lock.hcl tham chiếu tới phiên bản không còn tồn tại hoặc hash đã thay đổi
Private/custom registry không truy cập được — URL registry nội bộ sai hoặc thiếu thông tin xác thực

Fix 1: Kiểm Tra Kết Nối Mạng Tới Registry

Bắt đầu từ đây. Trước khi chỉnh bất kỳ cấu hình nào, hãy xác nhận máy bạn có thể kết nối tới registry hay không:

curl -I https://registry.terraform.io/.well-known/terraform.json

Timeout hoặc lỗi kết nối? Đó là vấn đề mạng — không phải lỗi cấu hình Terraform.

Đứng Sau Corporate Proxy

Thiết lập biến môi trường proxy trước khi chạy terraform init:

# Linux/macOS
export HTTPS_PROXY=https://your-proxy.company.com:8080
export HTTP_PROXY=http://your-proxy.company.com:8080
export NO_PROXY="localhost,127.0.0.1"

terraform init

# Windows (PowerShell)
$env:HTTPS_PROXY = "https://your-proxy.company.com:8080"
$env:HTTP_PROXY = "http://your-proxy.company.com:8080"

terraform init

Fix 2: Chạy terraform init -upgrade

Lock file cũ hoặc metadata cache lỗi thời? Buộc làm mới hoàn toàn:

terraform init -upgrade

Lệnh này tải lại metadata provider và ghi checksum mới vào .terraform.lock.hcl. State của bạn sẽ không bị ảnh hưởng.

Fix 3: Kiểm Tra Block required_providers

Mở versions.tf — hoặc nơi bạn đặt block terraform — và xác minh địa chỉ source và version constraint:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"  # Đảm bảo phiên bản này tồn tại trên registry
    }
  }
  required_version = ">= 1.3.0"
}

Các lỗi thường gặp:

Dùng source = "aws" thay vì source = "hashicorp/aws" — hoạt động được trong Terraform 0.12, nhưng lỗi từ 0.13+
Ghim vào đúng một patch version như = 3.114.0 khi nó không tồn tại — hãy dùng ~> 3.114 thay thế
Constraints mâu thuẫn giữa các module — root yêu cầu >= 4.0 nhưng child module lại yêu cầu < 4.0

Để xem các phiên bản thực sự tồn tại của một provider:

curl -s https://registry.terraform.io/v1/providers/hashicorp/aws/versions | python3 -m json.tool | grep '"version"' | head -20

Fix 4: Xóa Lock File và Khởi Tạo Lại

Lock file bị hỏng? Hash không khớp? Xóa sạch và bắt đầu lại từ đầu:

rm .terraform.lock.hcl
rm -rf .terraform/
terraform init

Terraform sẽ giải quyết các provider từ đầu. Commit lại lock file mới được tạo sau khi hoàn tất.

Fix 5: Dùng Filesystem Mirror (Môi Trường Air-Gapped / Offline)

Máy đích không có internet? Các CI runner và server air-gapped đều gặp phải vấn đề này. Giải pháp là tạo một local provider mirror.

Trên máy có kết nối internet, tải provider về:

terraform providers mirror /tmp/tf-mirror

Chuyển thư mục /tmp/tf-mirror sang môi trường đích. Sau đó chỉ định Terraform sử dụng nó qua ~/.terraformrc (Linux/macOS) hoặc %APPDATA%/terraform.rc (Windows):

provider_installation {
  filesystem_mirror {
    path    = "/opt/terraform-providers"
    include = ["registry.terraform.io/*/*"]
  }
  direct {
    exclude = ["registry.terraform.io/*/*"]
  }
}

Fix 6: Thông Tin Xác Thực Private Registry

Registry riêng tư cần thông tin xác thực. Thêm vào ~/.terraformrc:

credentials "app.terraform.io" {
  token = "your-token-here"
}

Hoặc dùng biến môi trường cho Terraform Cloud:

export TF_TOKEN_app_terraform_io="your-token-here"

Xác Nhận Đã Sửa Xong

Lệnh terraform init thành công sẽ kết thúc bằng:

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure.

Xác nhận provider đã được tải về thực sự:

ls .terraform/providers/registry.terraform.io/hashicorp/aws/

Bạn sẽ thấy một thư mục được đặt tên theo phiên bản provider và platform — ví dụ như 5.40.0/linux_amd64/.

Tham Khảo Nhanh: Nên Thử Fix Nào Trước

Lỗi DNS / no such host → Fix 1 (mạng/proxy)
Hash mismatch / checksum error → Fix 2 (-upgrade) hoặc Fix 4 (xóa lock file)
No available releases match constraints → Fix 3 (kiểm tra version constraints)
Air-gapped / không có internet → Fix 5 (filesystem mirror)
401 Unauthorized từ private registry → Fix 6 (thông tin xác thực)