{"record":{"id":"923b5bf7f3259d01","repo":"microsoft/autogen","slug":"kernel-self-kernel-name-is-not-installed","errorCode":null,"errorMessage":"Kernel {self._kernel_name} is not installed.","messagePattern":"Kernel (.+?) is not installed\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-ext/src/autogen_ext/code_executors/docker_jupyter/_docker_jupyter.py","lineNumber":262,"sourceCode":"        return DockerJupyterCodeResult(\n            exit_code=0, output=\"\\n\".join([str(output) for output in outputs]), output_files=output_files\n        )\n\n    async def restart(self) -> None:\n        \"\"\"(Experimental) Restart a new session.\"\"\"\n        # Use async client to restart kernel\n        if self._kernel_id is not None:\n            await self._jupyter_client.restart_kernel(self._kernel_id)\n        # Reset the clients to force recreation\n        if self._async_jupyter_kernel_client is not None:\n            await self._async_jupyter_kernel_client.stop()\n            self._async_jupyter_kernel_client = None\n\n    async def start(self) -> None:\n        \"\"\"(Experimental) Start a new session.\"\"\"\n        available_kernels = await self._jupyter_client.list_kernel_specs()\n        if self._kernel_name not in available_kernels[\"kernelspecs\"]:\n            raise ValueError(f\"Kernel {self._kernel_name} is not installed.\")\n        self._kernel_id = await self._jupyter_client.start_kernel(self._kernel_name)\n\n    def _save_image(self, image_data_base64: str) -> str:\n        \"\"\"Save image data to a file.\"\"\"\n        image_data = base64.b64decode(image_data_base64)\n        filename = f\"{uuid.uuid4().hex}.png\"\n        path = os.path.join(str(self._output_dir), filename)\n        with open(path, \"wb\") as f:\n            f.write(image_data)\n        return os.path.abspath(path)\n\n    def _save_html(self, html_data: str) -> str:\n        \"\"\"Save html data to a file.\"\"\"\n        filename = f\"{uuid.uuid4().hex}.html\"\n        path = os.path.join(str(self._output_dir), filename)\n        with open(path, \"w\") as f:\n            f.write(html_data)\n        return os.path.abspath(path)","sourceCodeStart":244,"sourceCodeEnd":280,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-ext/src/autogen_ext/code_executors/docker_jupyter/_docker_jupyter.py#L244-L280","documentation":"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.","triggerScenarios":"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.","commonSituations":"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'.","solutions":["List what is actually available: connect a JupyterClient to the server and inspect await client.list_kernel_specs(), then use one of those names.","Use the default kernel_name='python3', which the default image provides.","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."],"exampleFix":"# before\nexecutor = DockerJupyterCodeExecutor(jupyter_server=server, kernel_name=\"ir\")\nawait executor.start()  # ValueError: Kernel ir is not installed.\n\n# after\nexecutor = DockerJupyterCodeExecutor(jupyter_server=server, kernel_name=\"python3\")\nawait executor.start()","handlingStrategy":"validation","validationCode":"from autogen_ext.experimental.jupyter_client import JupyterClient\n\nasync def kernel_available(client: JupyterClient, kernel_name: str) -> bool:\n    specs = await client.list_kernel_specs()\n    return kernel_name in specs.get(\"kernelspecs\", {})","typeGuard":null,"tryCatchPattern":"try:\n    await executor.start()\nexcept ValueError as e:\n    if \"is not installed\" in str(e):\n        executor = DockerJupyterCodeExecutor(jupyter_server=server, kernel_name=\"python3\")\n        await executor.start()\n    else:\n        raise","preventionTips":["Check list_kernel_specs() before start() when kernel_name is configurable.","Install extra kernels in the custom image at build time, not runtime."],"tags":["jupyter","kernel","docker","executor"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}