Fix Ansible "UNREACHABLE" Error: Host Connection Troubleshooting

Fix Ansible "UNREACHABLE" Error: Host Connection Troubleshooting

The UNREACHABLE! error means Ansible cannot connect to a host via SSH. Here's how to diagnose and fix it.

See also: Ansible Conflicting Action Statements Error: Causes and Fixes

Common Causes and Fixes

1. Wrong SSH Credentials

# Test SSH manually first
ssh -i ~/.ssh/id_rsa user@hostname
# Check your inventory
# inventory.ini
[webservers]
web01 ansible_host=10.0.0.1 ansible_user=deploy ansible_ssh_private_key_file=~/.ssh/id_rsa

2. SSH Port is Not 22

[webservers]
web01 ansible_host=10.0.0.1 ansible_port=2222

3. Host Key Verification Failed

# Quick fix (not recommended for production)
export ANSIBLE_HOST_KEY_CHECKING=False
# Better: add host key
ssh-keyscan -H 10.0.0.1 >> ~/.ssh/known_hosts

4. Firewall Blocking SSH

# Test connectivity
nc -zv 10.0.0.1 22
telnet 10.0.0.1 22
# Check firewall on remote host
sudo ufw status
sudo iptables -L -n | grep 22

5. DNS Resolution Failure

# Check DNS
nslookup hostname
dig hostname
# Use IP directly in inventory
web01 ansible_host=10.0.0.1

6. SSH Timeout

# ansible.cfg
[defaults]
timeout = 30
[ssh_connection]
ssh_args = -o ConnectTimeout=30

Debugging Steps

# Run with verbose output
ansible webservers -m ansible.builtin.ping -vvvv
# Test specific host
ansible web01 -m ansible.builtin.ping -vvv
# Check SSH directly with Ansible's connection
ansible web01 -m ansible.builtin.raw -a "echo connected"

See also: Ansible Permission Denied on Remote Temp Path: Fix Every Cause

FAQ

What does UNREACHABLE mean in Ansible?

UNREACHABLE means Ansible's SSH connection to the host failed. The host may be down, the SSH port may be blocked, credentials may be wrong, or a network issue prevents connectivity.

How do I fix UNREACHABLE errors?

Verify the host is up: ping hostname Test SSH manually: ssh user@hostname Check inventory settings (host, port, user, key) Increase timeout in ansible.cfg Run with -vvvv for detailed error output

How do I skip unreachable hosts?

Use --forks 1 to process sequentially, or set ignore_unreachable: true on tasks that should continue despite unreachable hosts.

Related Articles

• Install Ansible: Complete Guide • Ansible Configuration Guide

7. Wrong Python Interpreter

# Host has Python in non-standard location
[webservers:vars]
ansible_python_interpreter = /usr/bin/python3

8. WinRM Issues (Windows Hosts)

# Windows UNREACHABLE usually means WinRM is not configured
# In inventory:
[windows:vars]
ansible_connection = winrm
ansible_winrm_transport = ntlm
ansible_winrm_port = 5985
ansible_winrm_scheme = http

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

See also: Ansible Template Error While Templating String: Fix Every Jinja2 Error

Complete Diagnostic Playbook

---
- name: Diagnose connection issues
  hosts: all
  gather_facts: false
  ignore_unreachable: true
tasks:
    - name: Test basic connectivity
      ansible.builtin.ping:
      register: ping_result
      ignore_errors: true
- name: Report unreachable hosts
      ansible.builtin.debug:
        msg: "{{ inventory_hostname }} is UNREACHABLE"
      when: ping_result.unreachable | default(false)
- name: Report reachable hosts
      ansible.builtin.debug:
        msg: "{{ inventory_hostname }} is reachable"
      when: ping_result is succeeded
- name: Summary
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Show results
      ansible.builtin.debug:
        msg: >
          Total hosts: {{ groups['all'] | length }}.
          Check verbose output above for unreachable hosts.

Quick Reference: UNREACHABLE Causes

| Cause | Test | Fix | |---|---|---| | Host is down | ping hostname | Start the host | | SSH not running | ssh user@host | Start sshd: systemctl start sshd | | Wrong port | nc -zv host 22 | Set ansible_port in inventory | | Firewall blocking | iptables -L -n | Open port 22 (or custom SSH port) | | Bad credentials | ssh -i key user@host | Fix ansible_user, ansible_ssh_private_key_file | | DNS failure | nslookup host | Use IP or fix DNS | | Timeout | Check network latency | Increase timeout in ansible.cfg | | Python missing | SSH and run python3 --version | Install Python or set ansible_python_interpreter |

Can I set a per-host timeout?

Yes. Use the ansible_timeout variable in inventory:

slow_host ansible_host=10.0.0.5 ansible_timeout=60

How do I handle mixed Linux and Windows inventories?

Separate them into groups with appropriate connection vars:

[linux]
web01 ansible_host=10.0.0.1
[windows]
win01 ansible_host=10.0.0.2
[linux:vars]
ansible_connection=ssh
[windows:vars]
ansible_connection=winrm
ansible_winrm_transport=ntlm