Troubleshooting 'Timeout waiting for SSH connection' in Packer

The SSH Connection Timeout Problem

When Packer attempts to provision a Linux image, it must establish a secure shell (SSH) connection to the temporary instance to execute scripts and configuration files. A "Timeout waiting for SSH connection" error occurs when the Packer runner cannot complete the TCP handshake or authenticate with the guest OS within the allocated time window.

The primary takeaway is that this failure is rarely a bug in Packer itself, but rather a disconnect between the network path, the guest OS state, or the authentication credentials.

Diagnostic Matrix

Use this table to match your observed symptoms to the most likely root cause.

Symptom	Likely Cause	Diagnostic Focus
Immediate failure or consistent timeout across all builds	Network/Firewall Block	Security Groups / ACLs
Intermittent timeouts or failure after several minutes	Slow Boot / SSH Daemon Lag	Instance Boot Logs
Connection established but authentication fails repeatedly	Credential Mismatch	Username / SSH Keys

Ordered Checks and Fixes

1. Verify Network Reachability

Packer requires a clear path to port 22 on the target instance. If you are running Packer from a CI/CD runner, the instance's security group must explicitly allow the runner's outbound IP.

• Check: Ensure the cloud security group allows inbound TCP port 22 from the build agent's IP address.
• Risk: Do not open port 22 to 0.0.0.0/0. This exposes your build instance to the public internet. Restrict access specifically to the build agent's IP address.

2. Validate Guest OS Readiness

If the base image is heavy or the cloud provider's disk I/O is throttled, the SSH daemon (sshd) may not be active by the time Packer begins its connection attempts.

The Fix: Increase the ssh_timeout value in your builder configuration. The default is often insufficient for complex base images.

# Example for amazon-ebs builder
source "amazon-ebs" {
  # ... other config
  ssh_username = "ubuntu"
  ssh_timeout  = "20m" # Increase from default to allow slow boots
}

Caution: Setting this value excessively high can mask underlying performance regressions in your base image that should be optimized.

3. Audit Authentication Credentials

Packer injects a public key into the instance during creation. If the ssh_username is incorrect, the connection will be rejected even if the network is open.

• Check: Confirm the username matches the image provider (e.g., ubuntu for Ubuntu AMIs, ec2-user for Amazon Linux, debian for Debian).
• Check: Ensure the SSH key path is correct and the key is in a format supported by the guest OS (OpenSSH format).

Verification and Debugging

Builder options can vary by plugin version; confirm exact parameter names against your builder's current documentation.

Detailed Logging

Run the build with the PACKER_LOG environment variable set to 1. This reveals the exact SSH commands and errors being returned by the guest.

# Run this in your terminal/shell
export PACKER_LOG=1
packer build template.json

Serial Console Inspection

Access the cloud provider's serial console (e.g., AWS EC2 Serial Console). Look for the following log entry to confirm the OS is actually ready:

sshd: Server listening on 0.0.0.0 port 22

Manual Connection Test

If the build hangs, do not terminate the instance immediately. Attempt to SSH into the instance manually from the same machine running Packer:

# Replace [IP] and [USER] with your build instance details
ssh -i /path/to/key [USER]@[IP]

If the manual connection fails, the issue is network or credential-based; if it succeeds, the issue is likely a Packer timeout setting.

Escalation Criteria

If the following conditions are met and the timeout persists, escalate the issue to your infrastructure or cloud provider team:

• The serial console shows sshd is running.
• The security group is confirmed to allow traffic from the runner's IP.
• Manual SSH from the runner to the instance fails with Connection timed out (indicating a routing or VPC-level block).

Rollback

Because this diagnostic process involves modifying configuration files and security groups, revert the following if the build fails for other reasons:

• Remove the ssh_timeout override to return to default timing.
• Delete the temporary security group rule allowing port 22 to the build agent.