Helm chart download failures occur when the Helm provider cannot retrieve the chart from a repository. Common causes include network issues, deprecated repositories, missing dependencies, or uncached chart repositories.
Fixes Error: Error installing helm release: failed to download chart
export HELM_DEBUG=1
terraform applyexport HELM_DEBUG=1terraform applyError: Error installing helm release: failed to download chart
This error indicates that Helm (either via CLI or Terraform provider) attempted to download a chart from a configured repository but failed during the download process. The error message is intentionally generic because it masks the underlying cause—the real error is suppressed unless debugging is enabled. This commonly happens during 'helm install' or 'terraform apply' operations when deploying applications to Kubernetes clusters.
Set the HELM_DEBUG=1 environment variable before running terraform apply. This will surface the actual underlying error instead of the generic 'failed to download' message.
export HELM_DEBUG=1
terraform applyThe detailed error output will help identify the specific cause.
Run 'helm repo update' to refresh the local repository cache with the latest chart information:
helm repo updateIf using an older/deprecated repository, update it to the official archive location:
helm repo add stable https://charts.helm.sh/stable --force-updateConfirm the repository URL is correct and matches the exact format expected. List your configured repositories:
helm repo listTest accessibility of the repository directly:
curl -I https://your-repo-url/index.yamlVerify the exact chart name and version exist:
helm search repo your-chart --versionsEnsure your environment can reach the chart repository. Test network connectivity:
ping charts.helm.sh
nslookup charts.helm.shIf behind a proxy, configure Helm to use it. If using private repositories, ensure credentials are correctly configured in your kubeconfig.
If the repository download continues to fail, use the full .tgz chart URL directly in your Terraform configuration:
resource "helm_release" "example" {
name = "example"
chart = "https://github.com/yourorg/yourrepo/releases/download/v1.0.0/chart-1.0.0.tgz"
}This bypasses repository caching and downloads the chart directly.
Ensure you're using a recent version of the Terraform Helm provider. Older versions may have compatibility issues with newer chart repositories or Helm versions:
terraform init -upgradeCheck the current Helm provider version in your state file and consider upgrading to the latest available.
When chart verification is enabled (using GPG keys), Helm requires access to a keyring file (pubring.gpg). If the keyring is missing or inaccessible, the download fails with a generic error message. Ensure keyring files are properly mounted or available in the environment. Helm 3.12.2+ resolved several download-related issues; if using an older version, upgrading may fix the problem. For OCI registry charts (oci://...), ensure Docker credentials are configured correctly, as OCI registries use different authentication mechanisms than traditional HTTP chart repositories.