AnsibleByExample

How to Fix Ansible Connection Failures: Complete Troubleshooting Guide

Beginneransibletroubleshootingerrorconnection
2024-01-016By Luca Berton

Lesson 1 of 20 in Production Playbooks

Production Playbooks and Troubleshooting — full curriculum
  1. 1. Advanced Playbook Structure & Execution Strategies
  2. 2. Deep Dive: Variable Precedence & Best Practices
  3. 3. Jinja2 Templating Beyond Basics
  4. 4. Advanced Conditionals
  5. 5. Loops Masterclass
  6. 6. Blocks, Rescue, Always (Error Handling)
  7. 7. Handlers Advanced
  8. 8. Change Control: changed_when, failed_when
  9. 9. Tags and Selective Runs
  10. 10. Performance Tuning
  11. 11. Delegation Patterns
  12. 12. Local Actions and Remote Actions
  13. 13. Dynamic Inventory & Runtime Host Management
  14. 14. Includes & Imports (Structuring Large Codebases)
  15. 15. Role Design Patterns
  16. 16. Ansible Galaxy & Collections in Real Projects
  17. 17. Working with APIs (uri + JSON workflows)
  18. 18. Testing and Linting (Quality Gates)
  19. 19. Advanced Debugging Playbook Failures
  20. 20. Capstone: Multi-Stage Deployment
View path overview →

Ansible connection failures are the most common errors when running playbooks. They occur when Ansible cannot establish a connection to the target host — usually via SSH for Linux or WinRM for Windows. This guide covers every major connection error, its root cause, and how to fix it.

Understanding Ansible Connection Types

Ansible supports multiple connection plugins:

PluginProtocolDefault PortUsed For
sshSSH22Linux/Unix hosts (default)
paramikoSSH22Legacy SSH fallback
winrmWinRM5985/5986Windows hosts
localNoneN/ARunning on the control node itself
dockerDocker APIN/ADocker containers
network_cliSSH22Network devices

Common SSH Connection Errors

1. Operation Timed Out

Error message:

fatal: [webserver]: UNREACHABLE! => {
    "msg": "Failed to connect to the host via ssh: ssh: connect to host 192.168.1.100 port 22: Operation timed out",
    "unreachable": true
}

Root causes:

  • Host is powered off or not booted
  • Network interface is disabled
  • Firewall blocking port 22
  • Wrong IP address or hostname
  • Network routing issue

Troubleshooting steps:

# 1. Test basic connectivity
ping 192.168.1.100

# 2. Test SSH port specifically
nc -zv 192.168.1.100 22
# or
telnet 192.168.1.100 22

# 3. Test SSH connection directly
ssh -vvv user@192.168.1.100

# 4. Check if the host's firewall allows SSH
# On the target host:
sudo firewall-cmd --list-services   # firewalld
sudo ufw status                      # UFW
sudo iptables -L -n | grep 22       # iptables

2. Permission Denied (Public Key)

Error message:

fatal: [webserver]: UNREACHABLE! => {
    "msg": "Failed to connect to the host via ssh: Permission denied (publickey,password)."
}

Root causes:

  • Wrong SSH key or key not loaded in ssh-agent
  • Wrong username
  • authorized_keys file missing or wrong permissions
  • SSH server configured to reject password authentication

Fix:

# Check your SSH key
ssh-add -l

# Add your key to the agent
ssh-add ~/.ssh/id_rsa

# Test with verbose output
ssh -vvv -i ~/.ssh/id_rsa user@192.168.1.100

# Fix permissions on the target
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

In your inventory, specify the key:

[webservers]
192.168.1.100 ansible_user=deploy ansible_ssh_private_key_file=~/.ssh/deploy_key

3. Host Key Verification Failed

Error message:

fatal: [webserver]: UNREACHABLE! => {
    "msg": "Failed to connect to the host via ssh: Host key verification failed."
}

Root causes:

  • First connection to the host (host key not in known_hosts)
  • Host was rebuilt/reinstalled (host key changed)

Fix for development:

# ansible.cfg
[defaults]
host_key_checking = False

Or per-host in inventory:

[webservers:vars]
ansible_ssh_common_args='-o StrictHostKeyChecking=no'

Fix for production (more secure):

# Accept the host key once
ssh-keyscan -H 192.168.1.100 >> ~/.ssh/known_hosts

# Or remove the old key and reconnect
ssh-keygen -R 192.168.1.100
ssh user@192.168.1.100  # Accept the new key

4. Connection Refused

Error message:

fatal: [webserver]: UNREACHABLE! => {
    "msg": "Failed to connect to the host via ssh: ssh: connect to host 192.168.1.100 port 22: Connection refused"
}

Root causes:

  • SSH service (sshd) is not running on the target
  • SSH is listening on a non-standard port

Fix:

# On the target host, start sshd
sudo systemctl start sshd
sudo systemctl enable sshd

# Check which port SSH is listening on
sudo ss -tlnp | grep ssh

If SSH uses a non-standard port:

[webservers]
192.168.1.100 ansible_port=2222

5. Too Many Authentication Failures

Error message:

Received disconnect from 192.168.1.100: Too many authentication failures

Root cause: ssh-agent has too many keys loaded, and the server disconnects after too many failed attempts.

Fix:

# Specify the exact key
ssh -o IdentitiesOnly=yes -i ~/.ssh/correct_key user@host

# In ansible.cfg
[ssh_connection]
ssh_args = -o IdentitiesOnly=yes

WinRM Connection Errors (Windows)

Basic WinRM Setup

[windows]
winserver ansible_host=192.168.1.200

[windows:vars]
ansible_user=Administrator
ansible_password=SecretPassword
ansible_connection=winrm
ansible_winrm_server_cert_validation=ignore
ansible_port=5985

Common WinRM Errors

"Connection refused" or "WinRM connection error":

# On the Windows target, enable WinRM:
winrm quickconfig -q
Enable-PSRemoting -Force

# Allow unencrypted for testing (not production!)
winrm set winrm/config/service @{AllowUnencrypted="true"}
winrm set winrm/config/service/auth @{Basic="true"}

"SSL certificate verification failed":

# In inventory
ansible_winrm_server_cert_validation=ignore

# Or use HTTPS with proper certs
ansible_port=5986
ansible_winrm_transport=certificate

Debugging Connection Issues

Use Verbose Mode

# Increasing levels of debug output
ansible webserver -m ping -v
ansible webserver -m ping -vv
ansible webserver -m ping -vvv    # Shows SSH command
ansible webserver -m ping -vvvv   # Maximum verbosity

Test with the ping Module

# Test Linux connectivity
ansible all -m ping

# Test Windows connectivity
ansible windows -m win_ping

Check Ansible Configuration

# Show effective configuration
ansible-config dump | grep -i ssh

# Show inventory
ansible-inventory --list

Enable SSH Connection Logging

# ansible.cfg
[ssh_connection]
ssh_args = -o LogLevel=DEBUG3

[defaults]
log_path = /tmp/ansible.log

Common ansible.cfg Connection Settings

[defaults]
remote_user = deploy
host_key_checking = False
timeout = 30

[ssh_connection]
ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o StrictHostKeyChecking=no
pipelining = True
retries = 3

[privilege_escalation]
become = True
become_method = sudo
become_user = root
become_ask_pass = False

Connection Troubleshooting Checklist

  1. ✅ Can you ping the host?
  2. ✅ Can you ssh user@host manually?
  3. ✅ Is the correct SSH key loaded? (ssh-add -l)
  4. ✅ Is the username correct? (ansible_user)
  5. ✅ Is the port correct? (ansible_port)
  6. ✅ Is the firewall allowing the connection?
  7. ✅ Is the SSH/WinRM service running on the target?
  8. ✅ Are file permissions correct? (~/.ssh/ = 700, keys = 600)
  9. ✅ Is host_key_checking disabled for new hosts?
  10. ✅ Does ansible -m ping host -vvvv show the actual error?

Conclusion

Connection failures are the first obstacle in any Ansible deployment. The vast majority are caused by SSH configuration issues — wrong keys, wrong ports, firewall rules, or missing services. Always start by testing the connection manually with ssh -vvv, then work through the troubleshooting checklist above. For Windows hosts, ensure WinRM is properly configured before attempting Ansible connections.

All Tutorials