What causes "Docker image push failed" in apache/kafka?

Run docker login with credentials that have push permission on the target namespace.

apache/kafka · error · SystemError

Docker image push failed

Error message

Docker image push failed

What it means

Raised by build_push() in docker/docker_release.py when any exception occurs during create_builder() or build_docker_image_runner(...) with the --push flag. Like build_docker_image_runner it is a bare except: that masks the underlying failure; the finally block still calls remove_builder() to clean up the buildx instance.

Source

Thrown at docker/docker_release.py:49

        docker_release <image> --kafka-url <kafka_url> --image-type <type>

        This command will build the multiarch image of type <type> (jvm by default),
        named <image> using <kafka_url> to download kafka and push it to the docker image name <image> provided.
        Make sure image is in the format of <registry>/<namespace>/<image_name>:<image_tag>.
"""

from datetime import date
import argparse

from common import execute, build_docker_image_runner

def build_push(image, kafka_url, image_type):
    try:
        create_builder()
        build_docker_image_runner(f"docker buildx build -f $DOCKER_FILE --build-arg kafka_url={kafka_url} --build-arg build_date={date.today()} --push \
              --platform linux/amd64,linux/arm64 --tag {image} $DOCKER_DIR", image_type)
    except:
        raise SystemError("Docker image push failed")
    finally:
        remove_builder()

def create_builder():
    execute(["docker", "buildx", "create", "--name", "kafka-builder", "--use"])

def remove_builder():
    execute(["docker", "buildx", "rm", "kafka-builder"])

if __name__ == "__main__":
    print("\
          This script will build and push docker images of apache kafka.\n \
          Please ensure that image has been sanity tested before pushing the image. \n \
          Please ensure you are logged in the docker registry that you are trying to push to.")
    parser = argparse.ArgumentParser()
    parser.add_argument("image", help="Dockerhub image that you want to push to (in the format <registry>/<namespace>/<image_name>:<image_tag>)")
    parser.add_argument("--image-type", "-type", choices=["jvm", "native"], default="jvm", dest="image_type", help="Image type you want to build")
    parser.add_argument("--kafka-url", "-u", dest="kafka_url", help="Kafka url to be used to download kafka binary tarball in the docker image")

View on GitHub (pinned to c31c9215e1)

Solutions

Run docker login <registry> with credentials that have push permission on the target namespace.
Confirm the image argument matches <registry>/<namespace>/<image_name>:<image_tag> (see docker_release.py:35,65).
Clean up any leftover builder: docker buildx rm kafka-builder, then retry.
Reproduce manually with the expanded command from docker_release.py:46-47 to see the real error (the wrapper hides it).

Example fix

# before
try:
    create_builder()
    build_docker_image_runner(f"docker buildx build ... --push ...", image_type)
except:
    raise SystemError("Docker image push failed")
# after (surface the underlying cause)
try:
    create_builder()
    build_docker_image_runner(f"docker buildx build ... --push ...", image_type)
except Exception as e:
    raise SystemError("Docker image push failed") from e

Defensive patterns

Strategy: retry

Validate before calling

# Verify registry login and target tag format before attempting push.
import re, subprocess
def preflight_push(image):
    if subprocess.run(["docker", "info"], capture_output=True).returncode != 0:
        raise RuntimeError("docker daemon unavailable")
    if subprocess.run(["docker", "buildx", "ls"], capture_output=True).returncode != 0:
        raise RuntimeError("buildx not installed")
    if not re.match(r'^[\w.-]+/[\w.-]+/[\w.-]+:[\w.-]+$', image):
        raise ValueError(f"image must be <registry>/<namespace>/<name>:<tag>, got {image}")

Type guard

# Only attempt a push if logged in to the registry and tag is well-formed.
def ready_to_push(image: str) -> bool:
    import re
    return bool(re.match(r'^[\w.-]+/[\w.-]+/[\w.-]+:[\w.-]+$', image))

Try / catch

from docker_release import build_push
import time
for attempt in range(1, 4):
    try:
        build_push(image, kafka_url, image_type)
        break
    except SystemError:
        if attempt == 3:
            raise
        time.sleep(2 ** attempt)  # registry/network hiccups often clear on retry

Prevention

Run 'docker login <registry>' (or 'docker buildx login') before invoking build_push; the script assumes an authenticated session.
Confirm the image tag is fully qualified <registry>/<namespace>/<name>:<tag>; missing registry prefix is a common cause of push failure.
Check that you have push permission on the target namespace and that the tag is not already immutably published.
For flaky network/registry errors, wrap build_push in a bounded retry (max 3, exponential backoff) rather than a single attempt.

When it happens

Trigger: Running docker_release.py build_push(image, kafka_url, image_type); the failure can originate in create_builder() (docker buildx create), in the buildx build itself, or specifically in the --push step (registry authentication, tag format, network).

Common situations: Not logged in to the docker registry (docker login), image tag not in <registry>/<namespace>/<image>:<tag> format, lack of push permission on the namespace, builder 'kafka-builder' left over from a prior failed run (so create_builder fails), or registry rate-limiting during the multi-arch push.

Related errors

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