How to fix Error: ssh: unable to authenticate in Terraform

TerraformINTERMEDIATEHIGHUpdated Dec 30, 2025· 151 views

This error occurs when Terraform's SSH client cannot authenticate with a remote server during provisioner operations. It typically indicates missing or misconfigured authentication credentials (private key, password, or SSH agent).

Quick fix

Fixes Error: ssh: unable to authenticate

ssh -i /path/to/private/key -u username@host.example.com
  1. Verify SSH works manually first
  2. Configure the connection block with private key
  3. Use SSH agent if key is password-protected
  4. Add timeout and retry logic for slow instances
terraform — error
ssh -i /path/to/private/key -u username@host.example.com
Error: ssh: unable to authenticate

What this error means

When Terraform attempts to connect to a remote host using SSH provisioners (remote-exec, file, etc.), it uses a built-in SSH client. This error appears when the SSH handshake completes but authentication fails because Terraform cannot present valid credentials to the server. The server rejects the connection because no supported authentication methods remain—either the credentials weren't provided, were in an unsupported format, or don't match what's configured on the remote host.

Typical symptoms

  • remote-exec or file provisioner fails immediately with SSH handshake error
  • Error message shows 'attempted methods [none publickey]' or similar
  • Manual SSH connection to the same host works fine
  • Connection succeeds but authentication fails before any commands run
  • Error occurs even though private key exists locally

Common causes

  1. Missing authentication configuration in the connection block (no private_key, password, or agent specified)
  2. Private key file path is incorrect or file doesn't exist
  3. Using private_key with key name instead of actual key content (missing file() interpolation)
  4. Private key is password-protected but Terraform SSH client doesn't support encrypted keys
  5. Private key permissions are too open (not 600) or SSH agent not available
  6. Remote instance hasn't finished bootstrapping SSH configuration (authorized_keys not yet set)
  7. Wrong SSH user specified for the operating system/AMI (should be ec2-user, ubuntu, centos, etc.)
  8. Private key on client doesn't match public key configured on remote instance

How to fix "Error: ssh: unable to authenticate"

1Verify SSH works manually first

Test if you can connect to the remote host using standard SSH command:

bash
ssh -i /path/to/private/key -u username@host.example.com

If manual SSH succeeds but Terraform fails, the issue is with Terraform's SSH configuration, not the connection itself. If manual SSH also fails, verify the key and host are correct before proceeding.

2Configure the connection block with private key

Add a proper connection block to your Terraform provisioner. Use the file() function to read the actual key contents, not just the key name:

hcl
resource "aws_instance" "example" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
  key_name      = "my-key"

  provisioner "remote-exec" {
    inline = ["echo Connected!"]

    connection {
      type        = "ssh"
      user        = "ec2-user"  # Use correct user for your AMI
      private_key = file("~/.ssh/my-key.pem")
      host        = self.public_ip
      timeout     = "5m"
    }
  }
}

The critical parts:
- Use file("path/to/key") not just the key name
- Specify correct user for your OS (ec2-user, ubuntu, centos, admin, etc.)
- Use host = the actual IP or hostname

3Use SSH agent if key is password-protected

If your private key is password-protected, Terraform cannot use it directly. Instead, use the SSH agent:

hcl
connection {
  type  = "ssh"
  user  = "ubuntu"
  agent = true  # Use SSH agent for key authentication
  host  = self.public_ip
}

Before running Terraform, ensure your key is loaded:

bash
ssh-add ~/.ssh/my-key.pem

This prompts for the passphrase once, then SSH agent handles authentication.

4Add timeout and retry logic for slow instances

Some cloud providers have delays before SSH is fully ready. Increase the timeout:

hcl
connection {
  type        = "ssh"
  user        = "ubuntu"
  private_key = file("~/.ssh/key.pem")
  host        = self.public_ip
  timeout     = "10m"  # Increased from default
}

If the remote instance takes time to configure authorized_keys, you can also add a small delay:

hcl
provisioner "remote-exec" {
  inline = ["echo Connected!"]

  connection {
    type        = "ssh"
    user        = "ubuntu"
    private_key = file("~/.ssh/key.pem")
    host        = self.public_ip
  }

  depends_on = [aws_instance.example]
}
5Verify private key permissions

SSH requires private keys to have restrictive permissions (600). Check your key:

bash
ls -l ~/.ssh/my-key.pem

Should show: -rw------- 1 user group (600 permissions)

Fix if needed:

bash
chmod 600 ~/.ssh/my-key.pem

Also verify the key format is correct (should start with -----BEGIN RSA PRIVATE KEY----- or -----BEGIN EC PRIVATE KEY-----).

6Try disabling SSH agent as fallback

If agent-based authentication has issues, try explicitly disabling it:

hcl
connection {
  type        = "ssh"
  user        = "ubuntu"
  private_key = file("~/.ssh/key.pem")
  host        = self.public_ip
  agent       = false  # Force key-based auth without agent
  timeout     = "5m"
}

This forces Terraform to use the private_key file directly instead of delegating to SSH agent.

Advanced notes

Advanced troubleshooting:

Amazon Linux 2023 Compatibility: Terraform 0.14.x has known issues authenticating with Amazon Linux 2023 (OpenSSH 8.7+). Upgrade to Terraform 1.0+ or use Amazon Linux 2 instead.

CoreOS/Fedora Issues: Some Linux distributions have SSH daemon behavior differences. If you can't connect with standard key auth, check if the distribution uses non-standard SSH configuration or SELinux policies that might block authentication.

Provider-specific SSH URIs: If using terraform-provider-libvirt or connecting via SSH URI (rather than standard provisioners), the SSH client path differs. Verify your provider's documentation for its specific connection requirements.

Debugging with TF_LOG: Set TF_LOG=DEBUG environment variable when running terraform apply to see detailed SSH negotiation logs, which can reveal exactly where authentication fails.

Frequently asked questions

What does "Error: ssh: unable to authenticate" mean?
), it uses a built-in SSH client. This error appears when the SSH handshake completes but authentication fails because Terraform cannot present valid credentials to the server. The server rejects the connection because no supported authentication methods remain—either the credentials weren't provided, were in an unsupported format, or don't match what's configured on the remote host.
How do I fix "Error: ssh: unable to authenticate"?
This error occurs when Terraform's SSH client cannot authenticate with a remote server during provisioner operations. It typically indicates missing or misconfigured authentication credentials (private key, password, or SSH agent).
What causes "Error: ssh: unable to authenticate"?
Missing authentication configuration in the connection block (no private_key, password, or agent specified) Private key file path is incorrect or file doesn't exist Using private_key with key name instead of actual key content (missing file() interpolation)
Is the "Error: ssh: unable to authenticate" 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