🚨 Ansible Error: 'SSH Error: data could not be sent to remote host' — Cause, Fix, and Troubleshooting Guide

Overview

This error means an SSH connection was established but then broke while Ansible was transferring data — pushing the module, reading results, or holding a persistent control connection. Unlike UNREACHABLE! on the first contact, this often appears mid-play:

fatal: [web-01]: UNREACHABLE! => {"changed": false, "msg": "SSH Error: data could not be sent to remote host. Make sure this host can be reached over ssh", "unreachable": true}

The connection worked at least briefly, then the pipe collapsed.

Symptoms

• Some tasks succeed, then a later task on the same host fails unreachable.
• Intermittent — re-running sometimes passes.
• Large file transfers (copy, synchronize) or long tasks trigger it most.

ansible-playbook -i inventory.ini site.yml -vvv

fatal: [web-01]: UNREACHABLE! => {"msg": "SSH Error: data could not be sent to remote host. Make sure this host can be reached over ssh"}

Common Root Causes

1. Stale or broken ControlPersist socket

Ansible reuses a multiplexed SSH connection. If that master socket dies (network blip, timeout), subsequent tasks fail even though a fresh SSH would work.

2. MTU / fragmentation over VPN or tunnels

A too-large MTU causes packets to be silently dropped mid-transfer, especially over WireGuard/IPsec.

3. Flaky network or aggressive firewall/idle timeout

A firewall or load balancer closes idle or long-lived connections; Wi-Fi drops; the host reboots mid-play.

4. Target overloaded or OOM

The host runs out of memory/CPU and sshd or the connection is killed while a heavy task runs.

How to diagnose

Reproduce with a raw connection and verbose SSH:

ansible web-01 -i inventory.ini -m ping -vvvv 2>&1 | grep -iE 'control|mux|ssh:'

Check for a stale control socket and clear it:

ls -la ~/.ansible/cp/ 2>/dev/null

Test MTU to the host (look for where large pings start failing):

ping -M do -s 1400 -c 2 10.0.4.21

Fixes

Reset SSH connection persistence

Disable or shorten ControlPersist while debugging:

# ansible.cfg
[ssh_connection]
ssh_args = -o ControlMaster=auto -o ControlPersist=60s

Or turn multiplexing off to isolate the issue:

[ssh_connection]
ssh_args = -o ControlMaster=no

Clear stale sockets:

rm -f ~/.ansible/cp/*

Keep the connection alive

# ansible.cfg
[ssh_connection]
ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o ServerAliveInterval=15 -o ServerAliveCountMax=3

Fix MTU on tunneled links

sudo ip link set dev wg0 mtu 1380

Reduce load and retry transient failures

Lower forks, or add retries to heavy tasks:

- name: Sync large artifact
  ansible.posix.synchronize:
    src: build/
    dest: /opt/app/
  register: r
  retries: 3
  delay: 5
  until: r is succeeded

What to watch out for

• Pipelining reduces round-trips and can help, but requires requiretty disabled in sudoers.
• Intermittent failures that only hit big transfers are almost always MTU or an idle-timeout firewall, not credentials.
• If the host reboots during a play (kernel update), expect this — gate reboots with ansible.builtin.reboot which waits for the host to return.

Related

• Ansible Error: ‘UNREACHABLE! Failed to connect to the host via ssh’
• Ansible Error: ‘A worker was found in a dead state’
• Tuning Ansible Performance: Forks, Pipelining, and Fact Caching