🚨 Ansible Error: 'unarchive Failed to find handler ... make sure the required command to extract the file is installed' — Cause, Fix, and Troubleshooting Guide

Overview

The unarchive module hands extraction off to a command on the target host — tar, gtar, unzip, or zipinfo depending on the archive format. If the right binary is missing on the managed node, the module cannot pick a handler:

fatal: [web-01]: FAILED! => {"changed": false, "msg": "Failed to find handler for '/tmp/app.zip'. Make sure the required command to extract the file is installed.\nCommand \"/usr/bin/unzip\" could not handle archive: /usr/bin/unzip not found\nCommand \"/usr/bin/zipinfo\" could not handle archive."}

The message lists each handler it tried and why each failed — usually a missing unzip.

Symptoms

• unarchive fails on a fresh/minimal host (containers, cloud base images).
• .zip files fail while .tar.gz works, or vice versa.
• The message names specific commands (unzip, zipinfo, gtar) that “could not handle” the archive.

ansible-playbook -i inventory.ini deploy.yml

TASK [Extract release] ******
fatal: [web-01]: FAILED! => {"msg": "Failed to find handler for '/tmp/release.zip'. Make sure the required command to extract the file is installed."}

Common Root Causes

1. unzip not installed (most common for .zip)

Minimal images often ship without unzip; the module has no way to open a zip.

2. tar/gtar missing or non-GNU

Some archives need GNU tar features; a BusyBox/BSD tar can fail to handle them.

3. Corrupt or wrong-type archive

The file is not actually the format its extension claims (truncated download, HTML error page saved as .zip).

4. Extracting on the controller vs target confusion

remote_src: false copies then extracts on the target; the handler still needs to exist on the target.

How to diagnose

Check for the extractor on the target:

ansible web-01 -i inventory.ini -m shell -a 'command -v unzip tar gtar; file /tmp/release.zip'

Verify the archive is valid:

ansible web-01 -i inventory.ini -m shell -a 'unzip -l /tmp/release.zip || tar -tzf /tmp/release.tgz'

Fixes

Install the extractor as a dependency

- name: Ensure unzip is present
  ansible.builtin.package:
    name: unzip
    state: present

- name: Extract release
  ansible.builtin.unarchive:
    src: release.zip
    dest: /opt/app
    remote_src: false

For tar-based archives on minimal hosts:

- name: Ensure tar/gzip
  ansible.builtin.package:
    name:
      - tar
      - gzip
    state: present

Re-fetch a possibly-corrupt archive

- name: Download release with checksum
  ansible.builtin.get_url:
    url: https://example.com/release.zip
    dest: /tmp/release.zip
    checksum: "sha256:{{ release_sha256 }}"

What to watch out for

• Order matters: install unzip/tar in an earlier task (or role dependency) before the unarchive task runs.
• get_url + checksum prevents extracting a truncated download that fails as “cannot handle archive.”
• In containers, prefer building the artifact in during image build; runtime extraction adds a package dependency to every base image.

Related

• Ansible Error: ‘No package matching found available’
• Ansible Error: ‘Could not find or access file on the Ansible Controller’
• Ansible Error: command not found / No such file or directory