ansible/ansible · error · AnsibleError

Unable to extract '%s' from collection

Error message

Unable to extract '%s' from collection

What it means

Raised in `_extract_tar_dir` when extracting a directory entry from a collection tarball and `tar.getmember(dirname)` raises KeyError, i.e. the tar archive has no member with that directory name. It means the collection tarball's manifest and its actual contents are out of sync.

Source

Thrown at lib/ansible/galaxy/collection/__init__.py:1690

    collection_output_path = _build_collection_dir(
        b_collection_path, b_collection_output_path,
        collection_manifest, file_manifest,
    )

    display.display(
        'Created collection for {coll!s} at {path!s}'.
        format(coll=collection, path=collection_output_path)
    )


def _extract_tar_dir(tar, dirname, b_dest):
    """ Extracts a directory from a collection tar. """
    dirname = to_native(dirname, errors='surrogate_or_strict')

    try:
        tar_member = tar.getmember(dirname)
    except KeyError:
        raise AnsibleError("Unable to extract '%s' from collection" % dirname)

    b_dir_path = os.path.join(b_dest, to_bytes(dirname, errors='surrogate_or_strict'))

    b_parent_path = os.path.dirname(b_dir_path)
    os.makedirs(b_parent_path, mode=S_IRWXU_RXG_RXO, exist_ok=True)

    if tar_member.type == tarfile.SYMTYPE:
        b_link_path = to_bytes(tar_member.linkname, errors='surrogate_or_strict')
        if not _is_child_path(b_link_path, b_dest, link_name=b_dir_path):
            raise AnsibleError("Cannot extract symlink '%s' in collection: path points to location outside of "
                               "collection '%s'" % (to_native(dirname), b_link_path))

        os.symlink(b_link_path, b_dir_path)

    else:
        if not os.path.isdir(b_dir_path):
            os.mkdir(b_dir_path, S_IRWXU_RXG_RXO)

View on GitHub (pinned to 9cf16a4aca)

Solutions

1. Re-download the collection tarball (verify sha256 if available) and retry the install
2. Rebuild the tarball with `ansible-galaxy collection build` so directory entries and metadata agree
3. Inspect the archive (`tar -tzf collection.tar.gz`) to confirm the missing dir entry, then fix the packaging script that created it

import tarfile

def tar_has_member(path, name):
    with tarfile.open(path) as tf:
        try:
            tf.getmember(name)
            return True
        except KeyError:
            return False

# verify required entries before install
assert tar_has_member('coll.tar.gz', 'MANIFEST.json')

from ansible.errors import AnsibleError
try:
    ansible.galaxy.collection install path
except AnsibleError as e:
    if "Unable to extract" in str(e):
        # re-download or rebuild tarball; log tar -tzf listing

When it happens

Trigger: Installing a tarball whose MANIFEST.json/file_info lists a directory (e.g. `plugins/`) but the tar contains no such member; typically a hand-built or corrupted tarball rather than one produced by `ansible-galaxy collection build`.

Common situations: Manually repacked/crafted collection tarballs, truncated downloads, tools that strip directory entries from tars, collections built with mismatched metadata.

Related errors

• Collection tar at '%s' does not contain the expected file '%
• The collection path specified '%s' is not a tarball, use 'an
• Not installing {collection_name} because GnuPG signature ver
• Cannot extract symlink '%s' in collection: path points to lo
• Checksum mismatch for '%s' inside collection at '%s'

AI-assisted analysis of ansible/ansible@9cf16a4aca (2026-08-15). Data as JSON: /api/errors/b9d2124e73bd9dbe. Report an issue: GitHub.