{"record":{"id":"f2a2e82e5caa1c96","repo":"microsoft/autogen","slug":"jupyter-server-must-be-a-jupyterconnectable-or-jup","errorCode":null,"errorMessage":"jupyter_server must be a JupyterConnectable or JupyterConnectionInfo.","messagePattern":"jupyter_server must be a JupyterConnectable or JupyterConnectionInfo\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-ext/src/autogen_ext/code_executors/docker_jupyter/_docker_jupyter.py","lineNumber":173,"sourceCode":"    component_config_schema = DockerJupyterCodeExecutorConfig\n    component_provider_override = \"autogen_ext.code_executors.docker_jupyter.DockerJupyterCodeExecutor\"\n\n    def __init__(\n        self,\n        jupyter_server: Union[JupyterConnectable, JupyterConnectionInfo],\n        kernel_name: str = \"python3\",\n        timeout: int = 60,\n        output_dir: Path | None = None,\n    ):\n        if timeout < 1:\n            raise ValueError(\"Timeout must be greater than or equal to 1.\")\n\n        if isinstance(jupyter_server, JupyterConnectable):\n            self._connection_info = jupyter_server.connection_info\n        elif isinstance(jupyter_server, JupyterConnectionInfo):\n            self._connection_info = jupyter_server\n        else:\n            raise ValueError(\"jupyter_server must be a JupyterConnectable or JupyterConnectionInfo.\")\n\n        self._output_dir = output_dir or getattr(jupyter_server, \"_bind_dir\", None)\n        if not self._output_dir:\n            with tempfile.TemporaryDirectory() as temp_dir:\n                self._output_dir = Path(temp_dir)\n                self._output_dir.mkdir(exist_ok=True)\n\n        self._jupyter_client = JupyterClient(self._connection_info)\n\n        self._kernel_name = kernel_name\n        self._timeout = timeout\n        self._async_jupyter_kernel_client: Optional[JupyterKernelClient] = None\n        self._kernel_id: Optional[str] = None\n\n    async def _ensure_async_kernel_client(self) -> JupyterKernelClient:\n        \"\"\"Ensure that an async kernel client exists and return it.\"\"\"\n        if self._kernel_id is None:\n            await self.start()","sourceCodeStart":155,"sourceCodeEnd":191,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-ext/src/autogen_ext/code_executors/docker_jupyter/_docker_jupyter.py#L155-L191","documentation":"Constructor validation in DockerJupyterCodeExecutor: the first argument must be either a JupyterConnectable (e.g. DockerJupyterServer) or a JupyterConnectionInfo object. Any other type (string URL, dict, None) is rejected with ValueError.","triggerScenarios":"Passing a connection URL string, a dict, or None as jupyter_server; passing a JupyterClient from a different package; using a similarly named class imported from the wrong module.","commonSituations":"Migrating from another Jupyter executor API that accepted URL strings, building connection info from JSON without constructing JupyterConnectionInfo, wrong imports (a similarly named class from a different library).","solutions":["Construct a DockerJupyterServer and pass it (or its .connection_info) into the executor.","If you already have host/port/token, build an explicit JupyterConnectionInfo(host=..., port=..., token=..., use_https=False).","Check the imported types come from autogen_ext.code_executors.docker_jupyter / autogen_core (not another package)."],"exampleFix":"# before\nexecutor = DockerJupyterCodeExecutor(jupyter_server=\"http://localhost:8888\")\n\n# after\nfrom autogen_ext.code_executors.docker_jupyter import DockerJupyterServer\nserver = DockerJupyterServer()\nexecutor = DockerJupyterCodeExecutor(jupyter_server=server)","handlingStrategy":"type-guard","validationCode":"from autogen_core.experimental.jupyter import JupyterConnectable, JupyterConnectionInfo\n\ndef usable_server(s: object) -> bool:\n    return isinstance(s, (JupyterConnectable, JupyterConnectionInfo))","typeGuard":"from typing_extensions import TypeGuard\nfrom autogen_core.experimental.jupyter import JupyterConnectable, JupyterConnectionInfo\n\ndef is_jupyter_server_arg(x: object) -> TypeGuard[JupyterConnectable | JupyterConnectionInfo]:\n    return isinstance(x, (JupyterConnectable, JupyterConnectionInfo))","tryCatchPattern":"try:\n    DockerJupyterCodeExecutor(jupyter_server=server)\nexcept ValueError as e:\n    if \"JupyterConnectable\" in str(e):\n        from autogen_ext.code_executors.docker_jupyter import DockerJupyterServer\n        executor = DockerJupyterCodeExecutor(jupyter_server=DockerJupyterServer())\n    else:\n        raise","preventionTips":["Construct servers via DockerJupyterServer rather than raw URLs or dicts.","Type-annotate the parameter at call sites so IDEs catch mismatches early."],"tags":["validation","constructor","jupyter","type-mismatch"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}