How to fix Error: dial tcp: connection refused in Terraform

TerraformINTERMEDIATEHIGHUpdated Dec 30, 2025· 193 views

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.

Quick fix

Fixes Error: dial tcp: connection refused

terraform plan -parallelism=5
terraform apply -parallelism=3
  1. Reduce parallelism to avoid overwhelming the target service
  2. Verify the target service is running and accessible
  3. Check provider configuration for correct endpoint
  4. Configure proxy settings if behind a corporate proxy
terraform — error
terraform plan -parallelism=5
terraform apply -parallelism=3
Error: dial tcp: connection refused

What this error means

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.

Typical symptoms

  • Terraform plan or apply commands fail with 'dial tcp: connection refused' error
  • Error appears intermittently, affecting different services on subsequent runs
  • Commands work in isolation but fail with increased parallelism
  • Error includes specific host and port information in the message
  • Local services or cloud provider APIs become unreachable during long operations

Common causes

  1. Excessive parallelism (default is 10) overwhelming target service's connection limits
  2. Provider endpoint or service is down, not running, or unreachable
  3. Incorrect provider configuration (wrong host, port, or endpoint URL)
  4. Firewall or security group blocking outbound connections
  5. DNS resolution failures preventing host lookup
  6. Network issues such as no internet connectivity or VPN disconnection
  7. Proxy misconfiguration when running behind corporate proxy
  8. SSH key missing or incorrect for provisioners

How to fix "Error: dial tcp: connection refused"

1Reduce parallelism to avoid overwhelming the target service

Terraform defaults to 10 concurrent operations. High parallelism can overwhelm provider APIs or services. Reduce it using the -parallelism flag:

bash
terraform plan -parallelism=5
terraform apply -parallelism=3

For persistent configuration, add to your terraform block:

hcl
terraform {
  required_version = ">= 1.0"
  required_providers {
    aws = {
      source = "hashicorp/aws"
    }
  }
}

Or use environment variable:

bash
export TF_CLI_ARGS_plan="-parallelism=5"
export TF_CLI_ARGS_apply="-parallelism=5"
terraform plan
2Verify the target service is running and accessible

Ensure the service or API endpoint that Terraform is trying to reach is actually running:

bash
# 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-number

If the service is down, restart it or ensure the VM/container is running.

3Check provider configuration for correct endpoint

Verify your provider block has the correct host, port, and endpoint configuration:

hcl
# 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.

4Configure proxy settings if behind a corporate proxy

If your network requires a proxy, set environment variables before running Terraform:

bash
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 plan

Verify the proxy configuration and that internal addresses are in the no_proxy list.

5Enable debug logging to identify the exact connection issue

Use TF_LOG environment variable to get detailed connection information:

bash
export TF_LOG=DEBUG
terraform plan 2>&1 | tee terraform-debug.log

For OCI Terraform provider, also enable OCI debug:

bash
export TF_LOG=DEBUG
export OCI_GO_SDK_DEBUG=v
terraform plan

Look for the specific host/port in the output to confirm the endpoint being contacted.

6Review firewall and security rules

Verify firewall rules allow outbound connections:

bash
# 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 policies

Ensure outbound rules allow connections to the provider endpoint. Cloud security groups should not block egress on the required ports.

Advanced notes

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").

Frequently asked questions

What does "Error: dial tcp: connection refused" mean?
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.
How do I fix "Error: dial tcp: connection refused"?
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.
What causes "Error: dial tcp: connection refused"?
Excessive parallelism (default is 10) overwhelming target service's connection limits Provider endpoint or service is down, not running, or unreachable Incorrect provider configuration (wrong host, port, or endpoint URL)
Is the "Error: dial tcp: connection refused" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading