microsoft/autogen · error · ValueError

Custom image {image_name} does not exist

Error message

Custom image {image_name} does not exist

What it means

Raised in DockerJupyterServer.__init__ when a custom image name is supplied but client.images.get() raises ImageNotFound. Unlike the default image path (which auto-builds), custom images must already exist locally; they are neither pulled nor built for you.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/code_executors/docker_jupyter/_jupyter_server.py:347

        # Determine and prepare Docker image
        image_name = custom_image_name or "autogen-jupyterkernelgateway"
        if not custom_image_name:
            try:
                client.images.get(image_name)
            except docker.errors.ImageNotFound:
                # Build default image if not found
                here = Path(__file__).parent
                dockerfile = io.BytesIO(self.DEFAULT_DOCKERFILE.encode("utf-8"))
                logging.info(f"Building image {image_name}...")
                client.images.build(path=str(here), fileobj=dockerfile, tag=image_name)
                logging.info(f"Image {image_name} built successfully")
        else:
            # Verify custom image exists
            try:
                client.images.get(image_name)
            except docker.errors.ImageNotFound as err:
                raise ValueError(f"Custom image {image_name} does not exist") from err
        if docker_env is None:
            docker_env = {}
        if token is None:
            token = DockerJupyterServer.GenerateToken()
        # Set up authentication token
        self._token = secrets.token_hex(32) if isinstance(token, DockerJupyterServer.GenerateToken) else token

        # Prepare environment variables
        env = {"TOKEN": self._token}
        env.update(docker_env)

        # Define volume configuration if bind directory is specified
        volumes = {str(self._bind_dir): {"bind": str(work_dir), "mode": "rw"}} if self._bind_dir else None

        # Start the container
        container = client.containers.run(
            image_name,
            detach=True,

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Build or pull the image first: docker build -t my-jupyter . or docker pull registry/my-jupyter, then construct DockerJupyterServer.
2. Verify with docker images | grep my-jupyter that the exact tag exists locally.
3. If you intended auto-build behavior, omit the custom image name so the default image is built instead.
4. If the tag was mistyped, correct it to match the locally built tag.

Example fix

# before
server = DockerJupyterServer(custom_image_name="mymage-typo")

# after
# docker build -t my-jupyter .
server = DockerJupyterServer(custom_image_name="my-jupyter")

import docker

def image_exists_locally(image_name: str) -> bool:
    try:
        docker.from_env().images.get(image_name)
        return True
    except docker.errors.ImageNotFound:
        return False

assert image_exists_locally("my-jupyter"), "build/pull the image before starting"

try:
    server = DockerJupyterServer(custom_image_name=name)
except ValueError as e:
    if "does not exist" in str(e):
        raise SystemExit(f"Run `docker build -t {name} .` first") from e
    raise

When it happens

Trigger: Constructing DockerJupyterServer with a custom image name that was never built/pulled on this machine, an image that exists only in a remote registry (no pull is attempted), or a mistyped tag.

Common situations: CI or fresh machines where the custom image was never built, forgetting to docker build before running tests, typos in the tag, images removed by docker system prune.

Related errors

• Timeout must be greater than or equal to 1.
• Module name must be a valid Python identifier
• No code blocks to execute.
• Timeout must be greater than or equal to 1.
• jupyter_server must be a JupyterConnectable or JupyterConnec

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/1a41d513d9e7a08d. Report an issue: GitHub.