{"record":{"id":"7617439c6129c4af","repo":"xai-org/grok-build","slug":"bind-127-0-0-1-port-e","errorCode":null,"errorMessage":"bind 127.0.0.1:{port}: {e}","messagePattern":"bind 127\\.0\\.0\\.1:(.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/codegen/xai-grok-diag-server/src/lib.rs","lineNumber":435,"sourceCode":"                    error = %e,\n                    \"failed to restrict diagnostics socket permissions\"\n                );\n            }\n            let task = tokio::spawn(async move {\n                if let Err(e) = axum::serve(listener, router(ctx)).await {\n                    tracing::warn!(error = %e, \"diagnostics server exited\");\n                }\n            });\n            Ok(BoundDiag {\n                addr: format!(\"unix:{}\", path.display()),\n                port: None,\n                task,\n            })\n        }\n        DiagListener::Tcp(port) => {\n            let listener = TcpListener::bind((Ipv4Addr::LOCALHOST, port))\n                .await\n                .map_err(|e| anyhow!(\"bind 127.0.0.1:{port}: {e}\"))?;\n            let local = listener.local_addr()?;\n            let task = tokio::spawn(async move {\n                if let Err(e) = axum::serve(listener, router(ctx)).await {\n                    tracing::warn!(error = %e, \"diagnostics server exited\");\n                }\n            });\n            Ok(BoundDiag {\n                addr: format!(\"http://{local}\"),\n                port: Some(local.port()),\n                task,\n            })\n        }\n    }\n}\n\n#[derive(Debug)]\npub struct BoundDiag {\n    /// Human-readable bound address for the startup log line.","sourceCodeStart":417,"sourceCodeEnd":453,"githubUrl":"https://github.com/xai-org/grok-build/blob/bc7f02eddd3d84085849dc19ed216f11c23b0571/crates/codegen/xai-grok-diag-server/src/lib.rs#L417-L453","documentation":"serve() failed to bind the diagnostics TCP listener on 127.0.0.1:{port}. Tokio's TcpListener::bind returned an OS error (address in use, permission denied, etc.) which is wrapped into this anyhow error. The diagnostics HTTP server cannot start, so all readiness/statusz checks against it fail.","triggerScenarios":"Starting the diag server with DiagListener::Tcp(port) when the port is already bound by another process, the port is privileged (<1024) without permissions, or ipv4 loopback bind fails for another OS reason.","commonSituations":"Two diag server instances running concurrently (stale process from a previous session); port collision with another dev service; CI containers reusing a fixed port; configured port 80/443 without root.","solutions":["Find and stop the process occupying the port (lsof -i :PORT / ss -ltnp), or kill the stale diag server","Choose a different, free port for the diagnostics listener","If binding a privileged port, run with sufficient privileges or pick a port >1024","Retry after a moment if a just-killed process is in TIME_WAIT"],"exampleFix":"// before\nDiagListener::Tcp(8080)\n// after\nDiagListener::Tcp(0) // let the OS pick a free ephemeral port, then read listener.local_addr()","handlingStrategy":"fallback","validationCode":"// probe the port before binding\nif std::net::TcpListener::bind((std::net::Ipv4Addr::LOCALHOST, port)).is_err() {\n    eprintln!(\"port {port} in use; pick another\");\n}\n","typeGuard":"fn port_free(port: u16) -> bool {\n    std::net::TcpListener::bind((std::net::Ipv4Addr::LOCALHOST, port)).is_ok()\n}","tryCatchPattern":"match serve(ctx, DiagListener::Tcp(port)).await {\n    Err(e) if e.to_string().contains(\"bind 127.0.0.1\") => {\n        eprintln!(\"diag TCP bind failed on {port}: {e:#}\");\n        // fallback: retry with port 0 to let the OS choose\n        serve(ctx, DiagListener::Tcp(0)).await\n    }\n    other => other,\n}","preventionTips":["Use port 0 (ephemeral) and read back listener.local_addr() in tests/CI","Ensure only one diag server instance runs per machine (pidfile or lock)","Avoid privileged ports (<1024) unless running with adequate privileges","Wait for TIME_WAIT to clear or set SO_REUSEADDR semantics via the runtime"],"tags":["network","bind","port-in-use","tcp","diagnostics"],"backgroundTag":"address-already-in-use","analyzedSha":"bc7f02eddd3d84085849dc19ed216f11c23b0571","analyzedAt":"2026-08-31T04:59:42.031Z","schemaVersion":2},"datasetVersion":"2026-08-31T09:17:48.483Z"}