microsoft/autogen · error · ValueError

jupyter_server must be a JupyterConnectable or JupyterConnec

Error message

jupyter_server must be a JupyterConnectable or JupyterConnectionInfo.

What it means

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.

Source

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

    component_config_schema = DockerJupyterCodeExecutorConfig
    component_provider_override = "autogen_ext.code_executors.docker_jupyter.DockerJupyterCodeExecutor"

    def __init__(
        self,
        jupyter_server: Union[JupyterConnectable, JupyterConnectionInfo],
        kernel_name: str = "python3",
        timeout: int = 60,
        output_dir: Path | None = None,
    ):
        if timeout < 1:
            raise ValueError("Timeout must be greater than or equal to 1.")

        if isinstance(jupyter_server, JupyterConnectable):
            self._connection_info = jupyter_server.connection_info
        elif isinstance(jupyter_server, JupyterConnectionInfo):
            self._connection_info = jupyter_server
        else:
            raise ValueError("jupyter_server must be a JupyterConnectable or JupyterConnectionInfo.")

        self._output_dir = output_dir or getattr(jupyter_server, "_bind_dir", None)
        if not self._output_dir:
            with tempfile.TemporaryDirectory() as temp_dir:
                self._output_dir = Path(temp_dir)
                self._output_dir.mkdir(exist_ok=True)

        self._jupyter_client = JupyterClient(self._connection_info)

        self._kernel_name = kernel_name
        self._timeout = timeout
        self._async_jupyter_kernel_client: Optional[JupyterKernelClient] = None
        self._kernel_id: Optional[str] = None

    async def _ensure_async_kernel_client(self) -> JupyterKernelClient:
        """Ensure that an async kernel client exists and return it."""
        if self._kernel_id is None:
            await self.start()

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Construct a DockerJupyterServer and pass it (or its .connection_info) into the executor.
2. If you already have host/port/token, build an explicit JupyterConnectionInfo(host=..., port=..., token=..., use_https=False).
3. Check the imported types come from autogen_ext.code_executors.docker_jupyter / autogen_core (not another package).

Example fix

# before
executor = DockerJupyterCodeExecutor(jupyter_server="http://localhost:8888")

# after
from autogen_ext.code_executors.docker_jupyter import DockerJupyterServer
server = DockerJupyterServer()
executor = DockerJupyterCodeExecutor(jupyter_server=server)

from autogen_core.experimental.jupyter import JupyterConnectable, JupyterConnectionInfo

def usable_server(s: object) -> bool:
    return isinstance(s, (JupyterConnectable, JupyterConnectionInfo))

from typing_extensions import TypeGuard
from autogen_core.experimental.jupyter import JupyterConnectable, JupyterConnectionInfo

def is_jupyter_server_arg(x: object) -> TypeGuard[JupyterConnectable | JupyterConnectionInfo]:
    return isinstance(x, (JupyterConnectable, JupyterConnectionInfo))

try:
    DockerJupyterCodeExecutor(jupyter_server=server)
except ValueError as e:
    if "JupyterConnectable" in str(e):
        from autogen_ext.code_executors.docker_jupyter import DockerJupyterServer
        executor = DockerJupyterCodeExecutor(jupyter_server=DockerJupyterServer())
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• Timeout must be greater than or equal to 1.
• Timeout must be greater than or equal to 1.
• Unsupported config type {config.GetType()}
• Messages should not be provided in options
• The agent name must be a valid Python identifier.

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