HKUDS/nanobot · error · TuiUnavailableError

the matching gateway instance is running on a different port

Error message

the matching gateway instance is running on a different port; restart it or use `nanobot agent --classic`

What it means

Error "the matching gateway instance is running on a different port; restart it or use `nanobot agent --classic`" thrown in HKUDS/nanobot.

Source

Thrown at nanobot/cli/tui_launcher.py:423

        GatewayClientLease,
        GatewayInstance,
        GatewayRuntime,
    )

    base_url, _bootstrap_secret = _tui_gateway_connection(config)
    instance = GatewayInstance.resolve(
        config_path=config_path,
        workspace=workspace_override,
    )
    runtime = GatewayRuntime(paths=instance.paths)
    lease = GatewayClientLease(runtime, kind="tui")
    lease.acquire()
    try:
        status = runtime.status()
        endpoint_reachable = _webui_endpoint_reachable(base_url)
        if status.running:
            if status.port not in {None, config.gateway.port}:
                raise TuiUnavailableError(
                    "the matching gateway instance is running on a different port; "
                    "restart it or use `nanobot agent --classic`"
                )
            if endpoint_reachable or not wait_until_ready:
                return _GatewayHandle(base_url=base_url, lease=lease)
        elif endpoint_reachable:
            raise TuiUnavailableError(
                "the configured gateway port belongs to a different nanobot instance; "
                "stop that instance or use `nanobot agent --classic`"
            )

        result = lease.ensure_on_demand_gateway(
            instance.start_options(port=config.gateway.port)
        )
        if not result.ok and result.message != "gateway_already_running":
            raise TuiUnavailableError(
                f"could not start the local gateway ({result.message}); "
                f"logs: {result.status.log_path}"

View on GitHub (pinned to 42f37dc4c0)

When it happens

Trigger: Thrown at nanobot/cli/tui_launcher.py:423 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of HKUDS/nanobot@42f37dc4c0 (2026-08-26). Data as JSON: /api/errors/bba2de24f84d35c3. Report an issue: GitHub.