apache/kafka · error · Exception

Unexpected contents in the artifact. Exactly one version dir

Error message

Unexpected contents in the artifact. Exactly one version directory is expected.

What it means

Raised by extract_artifact() in docker/extract_docker_official_image_artifact.py after unzipping a downloaded GitHub Actions artifact into a temp dir: the script expects exactly ONE top-level entry inside the zip (a single version directory). If iterdir() returns 0, 2, or more entries, the layout contract is broken and the script aborts rather than guessing which directory is canonical.

Source

Thrown at docker/extract_docker_official_image_artifact.py:58

def set_executable_permissions(directory):
    for root, _, files in os.walk(directory):
        for file in files:
            path = os.path.join(root, file)
            os.chmod(path, os.stat(path).st_mode | 0o111)


def extract_artifact(artifact_path):
    docker_official_images_dir = Path(os.path.dirname(os.path.realpath(__file__)), "docker_official_images")
    temp_dir = Path('temp_extracted')
    try:
        if temp_dir.exists():
            shutil.rmtree(temp_dir)  
        temp_dir.mkdir()
        with zipfile.ZipFile(artifact_path, 'r') as zip_ref:
            zip_ref.extractall(temp_dir)
        artifact_version_dirs = list(temp_dir.iterdir())
        if len(artifact_version_dirs) != 1:
            raise Exception("Unexpected contents in the artifact. Exactly one version directory is expected.")
        artifact_version_dir = artifact_version_dirs[0]
        target_version_dir =  Path(os.path.join(docker_official_images_dir, artifact_version_dir.name))
        target_version_dir.mkdir(parents=True, exist_ok=True)
        for image_type_dir in artifact_version_dir.iterdir():
            target_image_type_dir = Path(os.path.join(target_version_dir, image_type_dir.name))
            if target_image_type_dir.exists():
                shutil.rmtree(target_image_type_dir)            
            shutil.copytree(image_type_dir, target_image_type_dir)
            set_executable_permissions(target_image_type_dir)
    finally:
        if temp_dir.exists():
            shutil.rmtree(temp_dir)

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument("--path_to_downloaded_artifact", "-artifact_path", required=True,
                        dest="artifact_path", help="Path to zipped artifacy downloaded from github actions workflow.")
    args = parser.parse_args()

View on GitHub (pinned to c31c9215e1)

Solutions

1. Inspect the zip layout: unzip -l <artifact_path> and confirm there is exactly one top-level directory named like a version.
2. If extra hidden entries (e.g. __MACOSX) are present, repackage the zip with only the version directory at root.
3. Re-download the artifact from the GitHub Actions run that produced the official image, and verify its checksum.
4. If the producer workflow changed its packaging, update that workflow to emit a single version-rooted zip.

Example fix

# before (zip with files at root)
$ unzip -l artifact.zip
    Dockerfile
    entrypoint.sh
# after (zip with single version dir)
$ unzip -l artifact.zip
    3.7.0/Dockerfile
    3.7.0/entrypoint.sh
$ python docker/extract_docker_official_image_artifact.py --path_to_downloaded_artifact artifact.zip

# Inspect the artifact zip before extracting; require exactly one top-level version dir.
import zipfile, re, sys
def validate_artifact(artifact_path):
    with zipfile.ZipFile(artifact_path) as z:
        top = {n.split('/')[0] for n in z.namelist() if n}
    invalid = [d for d in top if not re.match(r'^\d+\.\d+\.\d+(\.[^.]+)?$', d)]
    if len(top) != 1 or invalid:
        sys.exit(f"Artifact must contain exactly one version directory, found: {sorted(top)}")

# True only when the zip contains a single top-level version-like directory.
def is_single_version_artifact(artifact_path) -> bool:
    import zipfile, re
    with zipfile.ZipFile(artifact_path) as z:
        top = {n.split('/')[0] for n in z.namelist() if n}
    return (len(top) == 1
            and bool(re.match(r'^\d+\.\d+\.\d+(\.[^.]+)?$', next(iter(top)))))

from extract_docker_official_image_artifact import extract_artifact
try:
    extract_artifact(artifact_path)
except Exception as e:
    if "Exactly one version directory is expected" in str(e):
        # List top-level entries so the operator can fix/repack the zip.
        import zipfile
        with zipfile.ZipFile(artifact_path) as z:
            print("Top-level entries:", sorted({n.split('/')[0] for n in z.namelist()}))
    raise

When it happens

Trigger: Calling extract_artifact(artifact_path) where the zip's top level contains !=1 entries. Causes: zip created without the conventional '<version>/...' root (files at archive root, or nested under multiple dirs), an empty/corrupt artifact, or the wrong artifact downloaded from the workflow run.

Common situations: Artifact re-packaged by CI in a way that flattened the version directory, multiple version directories zipped together, hidden files (e.g. macOS __MACOSX, .DS_Store) counted by iterdir(), or operator downloaded the wrong workflow artifact.

Related errors

• Failure in executing following command:-
• Docker Image Build failed
• Docker image push failed
• This field cannot be empty
• Invalid url in bootstrap.servers: {url}

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/89c37a5287af958d.json. Report an issue: GitHub.