{"record":{"id":"89c37a5287af958d","repo":"apache/kafka","slug":"unexpected-contents-in-the-artifact-exactly-one-v","errorCode":null,"errorMessage":"Unexpected contents in the artifact. Exactly one version directory is expected.","messagePattern":"Unexpected contents in the artifact\\. Exactly one version directory is expected\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"docker/extract_docker_official_image_artifact.py","lineNumber":58,"sourceCode":"def set_executable_permissions(directory):\n    for root, _, files in os.walk(directory):\n        for file in files:\n            path = os.path.join(root, file)\n            os.chmod(path, os.stat(path).st_mode | 0o111)\n\n\ndef extract_artifact(artifact_path):\n    docker_official_images_dir = Path(os.path.dirname(os.path.realpath(__file__)), \"docker_official_images\")\n    temp_dir = Path('temp_extracted')\n    try:\n        if temp_dir.exists():\n            shutil.rmtree(temp_dir)  \n        temp_dir.mkdir()\n        with zipfile.ZipFile(artifact_path, 'r') as zip_ref:\n            zip_ref.extractall(temp_dir)\n        artifact_version_dirs = list(temp_dir.iterdir())\n        if len(artifact_version_dirs) != 1:\n            raise Exception(\"Unexpected contents in the artifact. Exactly one version directory is expected.\")\n        artifact_version_dir = artifact_version_dirs[0]\n        target_version_dir =  Path(os.path.join(docker_official_images_dir, artifact_version_dir.name))\n        target_version_dir.mkdir(parents=True, exist_ok=True)\n        for image_type_dir in artifact_version_dir.iterdir():\n            target_image_type_dir = Path(os.path.join(target_version_dir, image_type_dir.name))\n            if target_image_type_dir.exists():\n                shutil.rmtree(target_image_type_dir)            \n            shutil.copytree(image_type_dir, target_image_type_dir)\n            set_executable_permissions(target_image_type_dir)\n    finally:\n        if temp_dir.exists():\n            shutil.rmtree(temp_dir)\n\nif __name__ == '__main__':\n    parser = argparse.ArgumentParser()\n    parser.add_argument(\"--path_to_downloaded_artifact\", \"-artifact_path\", required=True,\n                        dest=\"artifact_path\", help=\"Path to zipped artifacy downloaded from github actions workflow.\")\n    args = parser.parse_args()","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/apache/kafka/blob/996fb4585aa1bcc8980b0e1b8d6b168b986cd979/docker/extract_docker_official_image_artifact.py#L40-L76","documentation":"docker/extract_docker_official_image_artifact.py:extract_artifact unzips a release artifact into a temp dir and asserts that it contains exactly one top-level entry, which it treats as the version directory. If the zip has zero entries (empty) or more than one (e.g. multiple version dirs, a stray README at the root, or a nested layout), it raises Exception with this message.","triggerScenarios":"Passing a zip whose top level is anything other than a single directory - for example two sibling version folders, or files placed at the zip root alongside the version folder, or an empty zip.","commonSituations":"Uploading the wrong artifact (e.g. a tar.gz renamed to .zip, or a parent archive containing multiple version zips); CI producing an artifact with a top-level metadata file; manual repackaging that added a macOS __MACOSX folder.","solutions":["Inspect the artifact: `unzip -l artifact.zip` and confirm there is exactly one top-level directory.","Re-package so the version directory is the sole top-level entry (strip stray READMEs, __MACOSX, sibling dirs).","If multiple versions are legitimately present, extract only the target version dir and pass a single-version zip to this script.","Verify you are feeding the artifact produced by the official release process, not a staging bundle."],"exampleFix":"# before\n$ python3 docker/extract_docker_official_image_artifact.py mixed.zip\n# zip contains: 3.7.0/, 3.6.2/, README.md -> Exception: Unexpected contents...\n\n# after\n$ unzip -l single.zip\n   3.7.0/jvm/Dockerfile\n   3.7.0/native/Dockerfile\n$ python3 docker/extract_docker_official_image_artifact.py single.zip  # ok","handlingStrategy":"validation","validationCode":"import zipfile\nwith zipfile.ZipFile(artifact_path) as z:\n    roots = {n.split('/')[0] for n in z.namelist() if n}\nif len(roots) != 1:\n    raise SystemExit(f\"artifact must contain exactly one top-level dir, found: {sorted(roots)}\")","typeGuard":"null","tryCatchPattern":"try:\n    extract_artifact(artifact_path)\nexcept Exception as e:\n    print(f\"{e}; inspect with `unzip -l {artifact_path}`\", file=sys.stderr)\n    raise","preventionTips":["Inspect artifacts with `unzip -l` before feeding them to the script.","Repackage so a single version directory is the sole top-level entry.","Strip macOS __MACOSX and stray README files from release archives."],"tags":["docker","release-tools","artifact","validation","python","tooling"],"backgroundTag":null,"analyzedSha":"996fb4585aa1bcc8980b0e1b8d6b168b986cd979","analyzedAt":"2026-08-11T22:03:28.655Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}