HKUDS/nanobot · error · TuiUnavailableError

the configured gateway port belongs to a different nanobot…

Error message

the configured gateway port belongs to a different nanobot instance; stop that instance or use `nanobot agent --classic`

What it means

In _ensure_gateway, no managed nanobot gateway process is running for this instance, but the configured gateway port is already occupied by a reachable WebUI endpoint — i.e. another, unmanaged nanobot instance owns the port. Attaching would hit the wrong instance, so the launcher stops with instructions; the conflict is the foreign process on gateway.port.

Solutions

1. Stop the other nanobot instance holding the port
2. Change gateway.port in config to a free port
3. Use `nanobot agent --classic` if you do not need the native TUI

When it happens

Trigger: Thrown at nanobot/cli/tui_launcher.py:430 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/4eb7cd03f01a4c9a. Report an issue: GitHub.

Appendix: source

Thrown at nanobot/cli/tui_launcher.py:430

        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}"
            )

        if not wait_until_ready:
            return _GatewayHandle(base_url=base_url, lease=lease)

        deadline = time.monotonic() + 20
        while time.monotonic() < deadline:

View on GitHub (pinned to 42f37dc4c0)