HKUDS/nanobot · error · TuiUnavailableError

the matching gateway instance is running on a different…

Error message

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

What it means

In _ensure_gateway, a gateway process matching this instance is running, but its bound port differs from the configured gateway.port, so the TUI would attach to the wrong endpoint. The launcher refuses instead of guessing; the situation at fault is a stale gateway started under a different port configuration.

Solutions

1. Restart the gateway (`nanobot gateway restart`) so it binds the configured port
2. Align the gateway.port setting with the port the running instance uses
3. Use `nanobot agent --classic` to avoid the gateway-dependent native TUI

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.

Appendix: 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)