TLS handshake timeout occurs when Terraform cannot establish secure connections to remote servers, typically during provider installation or API calls. This is usually caused by network issues, firewall restrictions, or concurrent connection problems.
A TLS (Transport Layer Security) handshake timeout means Terraform tried to establish an encrypted connection to a remote server (like the plugin registry or cloud provider API) but the connection took too long to establish. The handshake is the process where both ends negotiate encryption settings. When it times out, it indicates either the server is slow to respond, the network is congested, or there's a connectivity issue between your machine and the server.
Set the TF_LOG environment variable to see detailed connection information:
export TF_LOG=DEBUG
terraform planThis shows which endpoint is timing out and helps narrow down the cause.
Test direct connectivity using curl with verbose output:
curl -v https://releases.hashicorp.comIf this fails, your network cannot reach the server. If it succeeds, the issue is specific to Terraform.
Lower the parallelism setting to reduce the number of simultaneous connections:
terraform plan -parallelism=1Start with parallelism=1 to test. If this works, gradually increase to find the threshold your network can handle.
Create or modify ~/.terraformrc to cache provider plugins:
plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"This prevents re-downloading the same providers, reducing connection load.
For Docker environments, especially on Google Cloud, verify MTU is set to 1460:
docker network inspect bridge | grep -i mtuIf needed, recreate the Docker network with proper MTU settings or adjust daemon.json:
{
"mtu": 1460
}Check if Terraform was installed via Homebrew or another third-party manager:
which terraform
terraform versionIf issues persist, download Terraform directly from https://www.terraform.io/downloads.html. If using a company VPN, try disconnecting temporarily to test if VPN policies are blocking connections. Finally, retry the operation as these are often intermittent issues that resolve on retry.
This error is particularly common in CI/CD environments running many parallel Terraform operations (like multiple terraform plan instances). If you encounter this in GitHub Actions, GitLab CI, or Jenkins, first try reducing parallelism. Some cloud providers throttle concurrent TLS connections, and breaking large operations into smaller sequential batches often resolves the issue. For rootless Docker or custom network configurations, MTU mismatches are a frequent cause. If running behind a corporate proxy or WAF (Web Application Firewall), work with your network team to ensure HashiCorp's plugin registry and your target cloud provider's APIs aren't being rate-limited. Go 1.7.4 had a known TLS handshake bug; if you control the Terraform build environment, ensure Go 1.7.3 or later (but not 1.7.4) is used.
Error: Error rendering template: template not found
How to fix "template not found" error in Terraform
Error: Error generating private key
How to fix 'Error generating private key' in Terraform
Error creating Kubernetes Service: field is immutable
How to fix "field is immutable" errors in Terraform
Error: Error creating local file: open: permission denied
How to fix "Error creating local file: permission denied" in Terraform
Error: line endings have changed from CRLF to LF
Line endings have changed from CRLF to LF in Terraform