{"record":{"id":"6b9edc7374b7cf1d","repo":"ansible/ansible","slug":"unknown-error-processing-manifest-directive-e","errorCode":null,"errorMessage":"Unknown error processing manifest directive: {e}","messagePattern":"Unknown error processing manifest directive: (.+?)","errorType":"exception","errorClass":"AnsibleError","httpStatus":null,"severity":"error","filePath":"lib/ansible/galaxy/collection/__init__.py","lineNumber":1174,"sourceCode":"\n        directives.extend([\n            f'exclude galaxy.yml galaxy.yaml MANIFEST.json FILES.json {namespace}-{name}-*.tar.gz',\n            'recursive-exclude tests/output **',\n            'global-exclude /.* /__pycache__ *.pyc *.pyo *.bak *~ *.swp',\n        ])\n\n    display.vvv('Manifest Directives:')\n    display.vvv(textwrap.indent('\\n'.join(directives), '    '))\n\n    u_collection_path = to_text(b_collection_path, errors='surrogate_or_strict')\n    m = Manifest(u_collection_path)\n    for directive in directives:\n        try:\n            m.process_directive(directive)\n        except DistlibException as e:\n            raise AnsibleError(f'Invalid manifest directive: {e}')\n        except Exception as e:\n            raise AnsibleError(f'Unknown error processing manifest directive: {e}')\n\n    manifest = _make_manifest()\n\n    for abs_path in m.sorted(wantdirs=True):\n        rel_path = os.path.relpath(abs_path, u_collection_path)\n        if os.path.isdir(abs_path):\n            manifest_entry = _make_entry(rel_path, 'dir')\n        else:\n            manifest_entry = _make_entry(\n                rel_path,\n                'file',\n                chksum_type='sha256',\n                chksum=secure_hash(abs_path, hash_func=sha256)\n            )\n\n        manifest['files'].append(manifest_entry)\n    return manifest\n","sourceCodeStart":1156,"sourceCodeEnd":1192,"githubUrl":"https://github.com/ansible/ansible/blob/9cf16a4aca7898481c257f1e17ad28d0b67b1f85/lib/ansible/galaxy/collection/__init__.py#L1156-L1192","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Read the embedded exception text to identify the failing directive and root cause","Check the collection tree for broken symlinks/permission problems: 'find . -xtype l' and 'ls -la'","Try upgrading (or pinning) distlib to a version matching what the ansible-core release was tested with","Reproduce with a minimal directives list to isolate the offending entry, then rewrite that directive"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"import os\n\ndef tree_walkable(root):\n    for dirpath, dirnames, filenames in os.walk(root):\n        for n in filenames:\n            p = os.path.join(dirpath, n)\n            if os.path.islink(p) and not os.path.exists(p):\n                return False  # broken symlink\n    return True","typeGuard":null,"tryCatchPattern":"from ansible.errors import AnsibleError\n\ntry:\n    build_collection(...)\nexcept AnsibleError as e:\n    if 'Unknown error processing manifest directive' in str(e):\n        # inspect embedded exception, check permissions/symlinks/filenames, isolate directive\n        ...","preventionTips":["Keep collection trees free of broken symlinks and unreadable files (CI: 'find . -xtype l')","Pin the distlib version used in CI to the one your ansible-core release was tested with"],"tags":["ansible-galaxy","build","manifest","distlib","filesystem","catch-all"],"backgroundTag":null,"analyzedSha":"9cf16a4aca7898481c257f1e17ad28d0b67b1f85","analyzedAt":"2026-08-15T00:15:47.100Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}