{"record":{"id":"bba2de24f84d35c3","repo":"HKUDS/nanobot","slug":"the-matching-gateway-instance-is-running-on-a-diff","errorCode":null,"errorMessage":"the matching gateway instance is running on a different port; restart it or use `nanobot agent --classic`","messagePattern":"the matching gateway instance is running on a different port; restart it or use `nanobot agent --classic`","errorType":"exception","errorClass":"TuiUnavailableError","httpStatus":null,"severity":"error","filePath":"nanobot/cli/tui_launcher.py","lineNumber":423,"sourceCode":"        GatewayClientLease,\n        GatewayInstance,\n        GatewayRuntime,\n    )\n\n    base_url, _bootstrap_secret = _tui_gateway_connection(config)\n    instance = GatewayInstance.resolve(\n        config_path=config_path,\n        workspace=workspace_override,\n    )\n    runtime = GatewayRuntime(paths=instance.paths)\n    lease = GatewayClientLease(runtime, kind=\"tui\")\n    lease.acquire()\n    try:\n        status = runtime.status()\n        endpoint_reachable = _webui_endpoint_reachable(base_url)\n        if status.running:\n            if status.port not in {None, config.gateway.port}:\n                raise TuiUnavailableError(\n                    \"the matching gateway instance is running on a different port; \"\n                    \"restart it or use `nanobot agent --classic`\"\n                )\n            if endpoint_reachable or not wait_until_ready:\n                return _GatewayHandle(base_url=base_url, lease=lease)\n        elif endpoint_reachable:\n            raise TuiUnavailableError(\n                \"the configured gateway port belongs to a different nanobot instance; \"\n                \"stop that instance or use `nanobot agent --classic`\"\n            )\n\n        result = lease.ensure_on_demand_gateway(\n            instance.start_options(port=config.gateway.port)\n        )\n        if not result.ok and result.message != \"gateway_already_running\":\n            raise TuiUnavailableError(\n                f\"could not start the local gateway ({result.message}); \"\n                f\"logs: {result.status.log_path}\"","sourceCodeStart":405,"sourceCodeEnd":441,"githubUrl":"https://github.com/HKUDS/nanobot/blob/42f37dc4c0e409eac7818a82d165c5f2757bc075/nanobot/cli/tui_launcher.py#L405-L441","documentation":"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.","triggerScenarios":"Thrown at nanobot/cli/tui_launcher.py:423 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Restart the gateway (`nanobot gateway restart`) so it binds the configured port","Align the gateway.port setting with the port the running instance uses","Use `nanobot agent --classic` to avoid the gateway-dependent native TUI"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"42f37dc4c0e409eac7818a82d165c5f2757bc075","analyzedAt":"2026-08-26T00:18:52.276Z","contentChangedAt":"2026-08-26T00:18:52.276Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}