microsoft/autogen · error · ValueError

Kernel {self._kernel_name} is not installed.

Error message

Kernel {self._kernel_name} is not installed.

What it means

Raised by DockerJupyterCodeExecutor.start(): it queries the Jupyter server's kernel specs and, if the requested kernel_name (default 'python3') is not among them, throws ValueError. The kernel runs inside the Docker image, so the kernel must be installed in that image, not on the host.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/code_executors/docker_jupyter/_docker_jupyter.py:262

        return DockerJupyterCodeResult(
            exit_code=0, output="\n".join([str(output) for output in outputs]), output_files=output_files
        )

    async def restart(self) -> None:
        """(Experimental) Restart a new session."""
        # Use async client to restart kernel
        if self._kernel_id is not None:
            await self._jupyter_client.restart_kernel(self._kernel_id)
        # Reset the clients to force recreation
        if self._async_jupyter_kernel_client is not None:
            await self._async_jupyter_kernel_client.stop()
            self._async_jupyter_kernel_client = None

    async def start(self) -> None:
        """(Experimental) Start a new session."""
        available_kernels = await self._jupyter_client.list_kernel_specs()
        if self._kernel_name not in available_kernels["kernelspecs"]:
            raise ValueError(f"Kernel {self._kernel_name} is not installed.")
        self._kernel_id = await self._jupyter_client.start_kernel(self._kernel_name)

    def _save_image(self, image_data_base64: str) -> str:
        """Save image data to a file."""
        image_data = base64.b64decode(image_data_base64)
        filename = f"{uuid.uuid4().hex}.png"
        path = os.path.join(str(self._output_dir), filename)
        with open(path, "wb") as f:
            f.write(image_data)
        return os.path.abspath(path)

    def _save_html(self, html_data: str) -> str:
        """Save html data to a file."""
        filename = f"{uuid.uuid4().hex}.html"
        path = os.path.join(str(self._output_dir), filename)
        with open(path, "w") as f:
            f.write(html_data)
        return os.path.abspath(path)

View on GitHub (pinned to 027ecf0a37)

Solutions

1. List what is actually available: connect a JupyterClient to the server and inspect await client.list_kernel_specs(), then use one of those names.
2. Use the default kernel_name='python3', which the default image provides.
3. If a custom image is used, install the kernel in it (e.g. for R: R -e 'IRkernel::installspec(user=FALSE)'), rebuild, and pass the image to DockerJupyterServer.

Example fix

# before
executor = DockerJupyterCodeExecutor(jupyter_server=server, kernel_name="ir")
await executor.start()  # ValueError: Kernel ir is not installed.

# after
executor = DockerJupyterCodeExecutor(jupyter_server=server, kernel_name="python3")
await executor.start()

from autogen_ext.experimental.jupyter_client import JupyterClient

async def kernel_available(client: JupyterClient, kernel_name: str) -> bool:
    specs = await client.list_kernel_specs()
    return kernel_name in specs.get("kernelspecs", {})

try:
    await executor.start()
except ValueError as e:
    if "is not installed" in str(e):
        executor = DockerJupyterCodeExecutor(jupyter_server=server, kernel_name="python3")
        await executor.start()
    else:
        raise

When it happens

Trigger: Calling await executor.start() with kernel_name set to a kernel (e.g. 'ir', 'javascript') that the Docker image does not include; using a custom image built without the desired kernel; a typo in kernel_name.

Common situations: Requesting non-Python kernels on the default image, custom Dockerfiles that overwrite the base image's kernelspecs, kernels registered on the host but not in the container, casing/spelling mistakes like 'Python3'.

Related errors

• Failed to connect to Docker. Please ensure Docker is install
• Unexpected error while connecting to Docker: {str(e)}
• Failed to start container from image {self._image}. Logs: {l
• Timeout must be greater than or equal to 1.
• Custom image {image_name} does not exist

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