AnsiblePilot — Master Ansible Automation

AnsiblePilot is the leading resource for learning Ansible automation, DevOps, and infrastructure as code. Browse over 1,400 tutorials covering Ansible modules, playbooks, roles, collections, and real-world examples. Whether you are a beginner or an experienced engineer, our step-by-step guides help you automate Linux, Windows, cloud, containers, and network infrastructure.

Popular Topics

About Luca Berton

Luca Berton is an Ansible automation expert, author of 8 Ansible books published by Apress and Leanpub including "Ansible for VMware by Examples" and "Ansible for Kubernetes by Example", and creator of the Ansible Pilot YouTube channel. He shares practical automation knowledge through tutorials, books, and video courses to help IT professionals and DevOps engineers master infrastructure automation.

Fix Ansible "UNREACHABLE" Error: Host Connection Troubleshooting

By Luca Berton · Published 2024-01-01 · Category: installation

How to fix Ansible UNREACHABLE error. Troubleshoot SSH connectivity, timeout, wrong port, firewall issues. Complete diagnosis and fix guide.

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?

  1. Verify the host is up: ping hostname
  2. Test SSH manually: ssh user@hostname
  3. Check inventory settings (host, port, user, key)
  4. Increase timeout in ansible.cfg
  5. 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.

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

CauseTestFix
Host is downping hostnameStart the host
SSH not runningssh user@hostStart sshd: systemctl start sshd
Wrong portnc -zv host 22Set ansible_port in inventory
Firewall blockingiptables -L -nOpen port 22 (or custom SSH port)
Bad credentialsssh -i key user@hostFix ansible_user, ansible_ssh_private_key_file
DNS failurenslookup hostUse IP or fix DNS
TimeoutCheck network latencyIncrease timeout in ansible.cfg
Python missingSSH and run python3 --versionInstall 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

Category: installation

Browse all Ansible tutorials · AnsiblePilot Home