Diagnosing Packer Communicator Timeouts in Cloud Builds

Recognizable Condition

When a Packer build stalls at the communicator stage you will see a log that looks like:

==> amazon-ebs: Waiting for SSH to become available...
==> amazon-ebs: Error: timed out waiting for SSH
==> amazon-ebs: Build failed.

or for Windows:

==> amazon-ebs: Waiting for WinRM to become available...
==> amazon-ebs: Error: timed out waiting for WinRM

Common Causes

These failures usually stem from networking, authentication, or timing issues.

Cause/Diagnostic Table

Symptom	Likely Cause	Initial Check
Timeout immediately (few seconds)	Security group or firewall blocks port 22/5985-5986	Verify SG rules from Packer host IP
Timeout after 5‑10 minutes	Instance takes longer to boot or missing public IP	Check instance state and networking in console
Authentication errors in log (e.g., “Permission denied”)	Wrong ssh_username or key pair	Test SSH manually with same key/username
Works locally but fails in CI	VPC routing or IAM role differences	Inspect subnet route tables and IAM trust policy

Ordered Checks

1. Confirm Instance State
   Open the cloud console (e.g., AWS EC2) and verify the instance is running. Note its public and private IPs.
2. Security Group Ingress
   Ensure the SG attached to the instance allows inbound traffic from the Packer host’s IP on the required port (22 for SSH, 5985/5986 for WinRM). Example SG rule:
   

   Type: SSH
   Protocol: TCP
   Port Range: 22
   Source: packer-host-ip/32

3. Manual SSH/WinRM Test
   From the same machine that runs Packer, try to connect manually:
   

   ssh -i /path/to/key.pem ssh_user@public_ip

   If this fails, the issue is network‑level, not Packer.
4. Review Communicator Settings
   Check the template for fields like ssh_timeout, ssh_interface, associate_public_ip_address, and ssh_username. Example snippet:
   

   builder "amazon-ebs" {
     region = "us-east-1"
     source_ami = "ami-0abcd1234efgh5678"
     instance_type = "t3.micro"
     ssh_username = "ec2-user"
     associate_public_ip_address = true
     ssh_timeout = "15m"
     communicator = "ssh"
   }

5. Check Subnet Routing
   If the instance has no public IP, ensure the subnet has a route to an Internet Gateway (IGW) or that you’re using a NAT gateway for outbound connectivity.
6. Validate IAM Role (for EC2)
   Confirm that the instance profile attached to the instance has the necessary EC2 permissions and that the Packer host can assume the role if using source_ami in an account with cross‑account access.

Fixes Tied to Findings

• Open the required port in the SG (or open a broader CIDR if testing).
• Set ssh_interface to private_ip if you’re using a bastion or session manager.
• Increase ssh_timeout for images that need more time to boot.
• Adjust ssh_username to the correct default user for the AMI (e.g., ubuntu, admin, ec2-user).
• Use associate_public_ip_address = true for instances that need to be reachable from the internet.
• If you’re in a private subnet, switch to communicator = "session_manager" and enable the AWS SSM agent on the image.

Escalation Criteria

1. If manual SSH/WinRM from the Packer host fails, the problem is infrastructure‑level: SG, VPC routing, or IAM. Escalate to network or cloud support.
2. If manual SSH works but Packer still times out, enable debug logging:
   

   export PACKER_LOG=1
   packer build template.pkr.hcl

   Inspect the handshake lines to see if Packer is using the wrong IP or interface.
3. If the debug log shows a Packer‑specific error (e.g., “ssh: handshake failed”) but no network error, confirm you’re using a supported builder plugin version (run packer plugins installed).

Practical Verification

After applying a fix, run a minimal build:

packer build -debug -only=amazon-ebs template.pkr.hcl

Check the output for the phrase “Waiting for SSH to become available” and verify it completes within the expected timeout. If it still stalls, revisit the ordered checks.

Limitations

• This guide focuses on SSH and WinRM communicators; other communicators (e.g., communicator = "winrm") have different defaults.
• Plugin versions may change default option names; always consult the docs for the specific builder plugin you’re using.
• Debug logs may contain sensitive keys; redact before sharing.