HKUDS/nanobot · error · TuiUnavailableError

could not start the local gateway

Error message

could not start the local gateway ({result.message}); logs: {result.status.log_path}

What it means

In _ensure_gateway, the on-demand gateway start via lease.ensure_on_demand_gateway() failed with a result other than ok and other than the benign 'gateway_already_running'. The error carries the runtime's own failure message plus the log file path; the fault is whatever the gateway runtime reported at spawn time (e.g. port bind failure, bad config).

Solutions

1. Read result.message and the referenced log file for the underlying cause
2. Fix the reported issue (commonly a port conflict or invalid channel config) and retry
3. Check that gateway.port is free and the config validates

When it happens

Trigger: Thrown at nanobot/cli/tui_launcher.py:439 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/8480848b4fd9ca44. Report an issue: GitHub.

Appendix: source

Thrown at nanobot/cli/tui_launcher.py:439

        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:
            if _webui_endpoint_reachable(base_url):
                current = runtime.status()
                if current.running and current.port in {None, config.gateway.port}:
                    return _GatewayHandle(base_url=base_url, lease=lease)
                break
            if not runtime.status().running and not _gateway_health_ready(
                config.gateway.host,
                config.gateway.port,
            ):

View on GitHub (pinned to 42f37dc4c0)