Fix: Ansible UNREACHABLE! Failed to connect to the host via ssh

You run a playbook or ansible -m ping and a host fails with:

fatal: [web1.example.com]: UNREACHABLE! => {"changed": false, "msg": "Failed to connect to the host via ssh: ssh: connect to host 192.0.2.10 port 22: Connection timed out", "unreachable": true}

UNREACHABLE is different from FAILED: Ansible never got a working connection, so no module ran on that host. It is counted under unreachable= in the PLAY RECAP. Ansible uses the normal OpenSSH client, so the part after Failed to connect to the host via ssh: is the SSH error itself. Read it first; it points straight at the cause.

Step 1: reproduce it with plain SSH

Find out which address, user and port Ansible uses, then try the same connection by hand.

ansible-inventory -i inventory.ini --host web1.example.com
ssh -p 22 [email protected]
ansible web1.example.com -i inventory.ini -m ping -vvvv

If plain ssh also fails, the problem is SSH or the network, not Ansible. -vvvv prints the exact ssh command Ansible runs, including user, key and options.

Step 2: match the message to the cause

1. Connection timed out or No route to host: the address is wrong or a firewall drops the traffic. Check ansible_host in the inventory, that the machine is up, and test the port with nc -zv 192.0.2.10 22.
2. Connection refused: the host is reachable but nothing listens on that port. sshd is stopped or runs on another port; set ansible_port if it is not 22.
3. Could not resolve hostname: the inventory name is not in DNS. Add ansible_host=IP or fix DNS.
4. Permission denied (publickey) (sometimes with more methods in the parentheses): SSH connected but authentication failed. Usually the wrong user (Ansible uses your local user name unless ansible_user or -u is set) or the wrong key. Point to the key with ansible_ssh_private_key_file or --private-key, or load it into ssh-agent with ssh-add.
5. Host key verification failed: the host is not in ~/.ssh/known_hosts, or its key changed after a reinstall. Connect once by hand with ssh and verify the fingerprint; for a rebuilt host remove the old entry with ssh-keygen -R 192.0.2.10 first.

Step 3: set the connection details in the inventory

[web]
web1.example.com ansible_host=192.0.2.10 ansible_port=22

[web:vars]
ansible_user=admin
ansible_ssh_private_key_file=~/.ssh/id_ed25519

If the servers only allow password logins, --ask-pass enables password authentication, but SSH keys with ssh-agent are the recommended setup.

About disabling host key checking

You can turn host key checking off with host_key_checking = False under [defaults] in ansible.cfg, or ANSIBLE_HOST_KEY_CHECKING=False. It makes the error go away, but it also removes protection against connecting to the wrong or a spoofed machine. Use it only for short-lived lab hosts, never as a general fix.

Still failing only in Ansible?

If plain ssh admin@host works but Ansible does not, compare the -vvvv output with your manual command: a different user, a different key, a ~/.ssh/config entry that matches the name you typed but not the IP Ansible uses, or a jump host configured only in your shell setup.

Official documentation

• Connection methods and details
• Building an inventory