This error occurs when Terraform cannot establish a TCP connection to a provider endpoint or service. Common causes include misconfigured provider settings, unreachable services, network issues, or excessive concurrent connections overwhelming the target server.
The 'dial tcp: connection refused' error indicates that Terraform attempted to establish a TCP connection to a specific host and port, but the connection was rejected. This typically means either the target service is not running on that address, the endpoint configuration is incorrect, a firewall is blocking access, or too many concurrent connections are being attempted simultaneously. The error can manifest when Terraform is trying to reach provider APIs, remote state backends, or managed services during plan or apply operations.
Terraform defaults to 10 concurrent operations. High parallelism can overwhelm provider APIs or services. Reduce it using the -parallelism flag:
terraform plan -parallelism=5
terraform apply -parallelism=3For persistent configuration, add to your terraform block:
terraform {
required_version = ">= 1.0"
required_providers {
aws = {
source = "hashicorp/aws"
}
}
}Or use environment variable:
export TF_CLI_ARGS_plan="-parallelism=5"
export TF_CLI_ARGS_apply="-parallelism=5"
terraform planEnsure the service or API endpoint that Terraform is trying to reach is actually running:
# For local services like Docker or Kubernetes
systemctl status docker
docker ps
kubectl cluster-info
# Test network connectivity to the endpoint
curl -v https://your-api-endpoint.example.com
telnet hostname port-number
nc -zv hostname port-numberIf the service is down, restart it or ensure the VM/container is running.
Verify your provider block has the correct host, port, and endpoint configuration:
# Kubernetes provider
provider "kubernetes" {
host = "https://localhost:6443"
token = var.token
}
# Docker provider
provider "docker" {
host = "unix:///var/run/docker.sock" # Linux
# host = "npipe:////.//pipe//docker_engine" # Windows
}
# Custom provider with endpoint
provider "myservice" {
host = "https://api.myservice.com:443"
port = 443
}Ensure the host and port match your actual service configuration.
If your network requires a proxy, set environment variables before running Terraform:
export http_proxy=http://proxy.company.com:8080
export https_proxy=http://proxy.company.com:8080
export no_proxy=localhost,127.0.0.1,internal.company.com
terraform planVerify the proxy configuration and that internal addresses are in the no_proxy list.
Use TF_LOG environment variable to get detailed connection information:
export TF_LOG=DEBUG
terraform plan 2>&1 | tee terraform-debug.logFor OCI Terraform provider, also enable OCI debug:
export TF_LOG=DEBUG
export OCI_GO_SDK_DEBUG=v
terraform planLook for the specific host/port in the output to confirm the endpoint being contacted.
Verify firewall rules allow outbound connections:
# Linux - check firewall status
sudo ufw status
sudo firewall-cmd --list-all
# Windows - check Windows Firewall
netsh advfirewall show allprofiles
# AWS Security Group - check egress rules
# Azure - check Network Security Group rules
# GCP - check Firewall policiesEnsure outbound rules allow connections to the provider endpoint. Cloud security groups should not block egress on the required ports.
Kubernetes + AWS EKS: When using Kubernetes and AWS providers together in a single apply, Terraform tries to configure the Kubernetes provider before the EKS cluster is created, causing connection refused errors. Solution: Use separate Terraform states or modules - manage EKS cluster in one apply, then separately manage Kubernetes resources. DNS Issues in Containers: Docker containers sometimes have DNS resolution issues (e.g., connection refused when looking up registry.terraform.io). Add --dns flag when running containers: docker run --dns 8.8.8.8 .... Rate Limiting: Some cloud providers rate-limit API connections. If errors are intermittent and always affect different services, reduce parallelism and add retry logic. Provisioner Timeouts: SSH provisioners timing out is often an SSH key issue, not network. Verify correct private key is configured: private_key = file("~/.ssh/id_rsa").
Error: Error installing helm release: cannot re-use a name that is still in use
How to fix "release name in use" error in Terraform with Helm
Error: Error creating GKE Cluster: BadRequest
BadRequest error creating GKE cluster in Terraform
Error: External program failed to produce valid JSON
External program failed to produce valid JSON
Error: Unsupported argument in child module call
How to fix "Unsupported argument in child module call" in Terraform
Error: network is unreachable
How to fix "network is unreachable" in Terraform