How to fix Error: remote-exec provisioner error in Terraform

What this error means

Terraform's remote-exec provisioner is designed to run commands on a remote machine (usually after creation). When this error appears, it means Terraform couldn't successfully execute one or more commands on the target instance. This could be because the connection itself failed, authentication didn't work, the instance wasn't ready yet, or the command itself encountered an error. The provisioner logs may not always provide clear details about what went wrong, making troubleshooting challenging.

Typical symptoms

• Terraform apply fails with 'Error: remote-exec provisioner error'
• Error occurs after resource creation completes
• Commands hang for several minutes before timing out
• Different results in different environments (dev vs. prod)
• Works manually via SSH/RDP but fails in Terraform

Common causes

1. SSH/WinRM connection blocked by security groups or firewall rules
2. Instance not fully booted or SSH service not ready when provisioner runs
3. Incorrect or missing private key for SSH authentication
4. Wrong username for the target instance (varies by OS: ec2-user, ubuntu, admin, etc.)
5. Network unreachability - instance has no public IP or no route to your network
6. Connection timeout too short for large scripts or slow networks
7. Script stored in /tmp but system hardened to prevent /tmp execution
8. Remote machine missing scp (required for file uploads) or shell interpreter
9. Script contains syntax errors or references missing tools/dependencies
10. Insufficient permissions on remote user account to execute commands

How to fix "Error: remote-exec provisioner error"

resource "aws_security_group" "example" {
  name = "allow_ssh"

  ingress {
    from_port   = 22
    to_port     = 22
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]  # Restrict this to your IP in production
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

# Test SSH connectivity
ssh -i /path/to/key.pem ec2-user@<instance-ip>

# Test WinRM connectivity (Windows)
winrm id -r:https://<instance-ip>:5986

resource "aws_instance" "example" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
}

# Add a small delay to allow SSH to be ready
resource "time_sleep" "wait_for_instance" {
  depends_on      = [aws_instance.example]
  create_duration = "30s"
}

resource "null_resource" "remote_exec" {
  depends_on = [time_sleep.wait_for_instance]

  provisioner "remote-exec" {
    inline = ["echo 'Instance ready'"]

    connection {
      type        = "ssh"
      user        = "ec2-user"
      private_key = file("~/.ssh/id_rsa")
      host        = aws_instance.example.public_ip
    }
  }
}

resource "null_resource" "example" {
  provisioner "remote-exec" {
    inline = [
      "sudo yum install -y httpd",
      "sudo systemctl start httpd"
    ]

    connection {
      type        = "ssh"
      user        = "ec2-user"              # Varies by AMI: ubuntu, admin, ec2-user, root, etc.
      private_key = file("~/.ssh/my-key.pem")
      host        = aws_instance.example.public_ip
      timeout     = "5m"
    }
  }

  depends_on = [aws_instance.example, aws_security_group.example]
}

provisioner "remote-exec" {
  connection {
    type        = "ssh"
    host        = aws_instance.example.public_ip
    user        = "ec2-user"
    private_key = file("~/.ssh/id_rsa")
    timeout     = "10m"  # Increased from default 5m
  }

  inline = ["echo 'Provisioning...'"]
}

TF_LOG=DEBUG terraform apply 2>&1 | tee terraform_debug.log

provisioner "remote-exec" {
  connection {
    type            = "ssh"
    host            = aws_instance.example.public_ip
    user            = "ec2-user"
    private_key     = file("~/.ssh/id_rsa")
    script_path     = "/home/ec2-user/terraform-script.sh"  # Use home directory instead
  }

  inline = ["echo 'Testing from home directory'"]
}

ssh -i ~/.ssh/id_rsa ec2-user@<instance-ip>

# Once connected, run your commands
sudo yum install -y httpd
sudo systemctl start httpd

resource "aws_instance" "example" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"

  user_data = base64encode(file("${path.module}/init-script.sh"))
}

user_data = base64gzip(templatefile("${path.module}/cloud-init.yaml", {
  packages : ["httpd"]
}))

Advanced notes

Frequently asked questions

What does "Error: remote-exec provisioner error" mean?

Terraform's remote-exec provisioner is designed to run commands on a remote machine (usually after creation). When this error appears, it means Terraform couldn't successfully execute one or more commands on the target instance. This could be because the connection itself failed, authentication didn't work, the instance wasn't ready yet, or the command itself encountered an error.

How do I fix "Error: remote-exec provisioner error"?

The remote-exec provisioner failed to execute scripts on a remote resource. This typically occurs due to connectivity issues, authentication failures, or timeout problems when Terraform tries to run commands over SSH or WinRM.

What causes "Error: remote-exec provisioner error"?

SSH/WinRM connection blocked by security groups or firewall rules Instance not fully booted or SSH service not ready when provisioner runs Incorrect or missing private key for SSH authentication

Is the "Error: remote-exec provisioner error" error serious?

Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Related errors

• Error: Removed block with invalid resource address

  Invalid resource address in Terraform removed block

  MEDIUM

• Error: Reference to undeclared module

  Reference to undeclared module in Terraform

  HIGH

• Error: replace_triggered_by argument is invalid

  How to fix "replace_triggered_by argument is invalid" in Terraform

  MEDIUM

• Error: Reference to undeclared input variable

  How to fix 'Reference to undeclared input variable' in Terraform

  HIGH

• context deadline exceeded

  Context deadline exceeded in Terraform

  HIGH

• resource is tainted, so must be replaced

  Resource is tainted, so must be replaced

  HIGH

Official resources & further reading

• 📚Terraform Official Documentation
• 📖
  Terraform Remote-Exec Provisioner Documentation(Official Docs)
• 📖
  Terraform Provisioners: When to Use Them(Official Docs)
• HashiCorp Community: Remote-Exec Provisioner Errors
• Scalr: Remote-Exec Provisioner Guide