ansible/ansible · error · AnsibleError

Unknown error processing manifest directive: {e}

Error message

Unknown error processing manifest directive: {e}

What it means

Raised by _build_files_manifest_distlib when Manifest.process_directive raises any exception that is not a DistlibException — an unexpected failure while applying a manifest directive (filesystem errors, encoding issues, bugs in directive handling). The original exception text is embedded for diagnosis. It is the catch-all sibling of the 'Invalid manifest directive' error.

Source

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

        directives.extend([
            f'exclude galaxy.yml galaxy.yaml MANIFEST.json FILES.json {namespace}-{name}-*.tar.gz',
            'recursive-exclude tests/output **',
            'global-exclude /.* /__pycache__ *.pyc *.pyo *.bak *~ *.swp',
        ])

    display.vvv('Manifest Directives:')
    display.vvv(textwrap.indent('\n'.join(directives), '    '))

    u_collection_path = to_text(b_collection_path, errors='surrogate_or_strict')
    m = Manifest(u_collection_path)
    for directive in directives:
        try:
            m.process_directive(directive)
        except DistlibException as e:
            raise AnsibleError(f'Invalid manifest directive: {e}')
        except Exception as e:
            raise AnsibleError(f'Unknown error processing manifest directive: {e}')

    manifest = _make_manifest()

    for abs_path in m.sorted(wantdirs=True):
        rel_path = os.path.relpath(abs_path, u_collection_path)
        if os.path.isdir(abs_path):
            manifest_entry = _make_entry(rel_path, 'dir')
        else:
            manifest_entry = _make_entry(
                rel_path,
                'file',
                chksum_type='sha256',
                chksum=secure_hash(abs_path, hash_func=sha256)
            )

        manifest['files'].append(manifest_entry)
    return manifest

View on GitHub (pinned to 9cf16a4aca)

Solutions

1. Read the embedded exception text to identify the failing directive and root cause
2. Check the collection tree for broken symlinks/permission problems: 'find . -xtype l' and 'ls -la'
3. Try upgrading (or pinning) distlib to a version matching what the ansible-core release was tested with
4. Reproduce with a minimal directives list to isolate the offending entry, then rewrite that directive

import os

def tree_walkable(root):
    for dirpath, dirnames, filenames in os.walk(root):
        for n in filenames:
            p = os.path.join(dirpath, n)
            if os.path.islink(p) and not os.path.exists(p):
                return False  # broken symlink
    return True

from ansible.errors import AnsibleError

try:
    build_collection(...)
except AnsibleError as e:
    if 'Unknown error processing manifest directive' in str(e):
        # inspect embedded exception, check permissions/symlinks/filenames, isolate directive
        ...

When it happens

Trigger: A directive that passes syntax checks but fails at filesystem level: unreadable/unstatable files, surrogate-escape encoding problems in filenames, permission errors during directory walks, or an distlib-internal edge case (e.g. symlink loops).

Common situations: Building in restricted CI containers where files are unreadable; exotic filenames with invalid UTF-8; broken symlinks inside the collection tree; distlib version drift after a Python upgrade.

Related errors

• Use of "manifest" requires the python "distlib" library
• Invalid manifest directive: {e}
• The output collection artifact '%s' already exists, but is a
• The file '%s' already exists. You can use --force to re-crea
• "build_ignore" and "manifest" are mutually exclusive

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