{"record":{"id":"87027a93fc44487e","repo":"pbakaus/impeccable","slug":"error-listen-eaddrinuse","errorCode":null,"errorMessage":"Error: listen EADDRINUSE: {}\n","messagePattern":"Error: listen EADDRINUSE: (.+?)\n","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/context/src/serve_question.rs","lineNumber":417,"sourceCode":"                return 1;\n            }\n        },\n        None => io.stdin().to_string(),\n    };\n    let detached_key = if a.has(\"detached-serve\") { a.arg(\"key\") } else { None };\n    let state = Arc::new(Mutex::new(ServerState::new(cwd.clone(), qdir.clone(), detached_key.clone(), idle_grace_ms)));\n    {\n        let mut st = state.lock().unwrap();\n        if let Err(msg) = st.load_round(&raw) {\n            io.err(&format!(\"serve-question: {}\\n\", msg));\n            return 1;\n        }\n    }\n    let port = if port_arg.is_finite() && port_arg >= 0.0 { port_arg as u16 } else { 0 };\n    let server = match tiny_http::Server::http((\"127.0.0.1\", port)) {\n        Ok(s) => s,\n        Err(e) => {\n            io.err(&format!(\"Error: listen EADDRINUSE: {}\\n\", e));\n            return 1;\n        }\n    };\n    let actual_port = server.server_addr().to_ip().map(|a| a.port()).unwrap_or(port);\n    let url = format!(\"http://127.0.0.1:{}/\", actual_port);\n    if a.has(\"detached-serve\") {\n        let _ = std::fs::create_dir_all(&qdir);\n        let key = a.arg(\"key\").unwrap_or_default();\n        let st = json!({ \"pid\": std::process::id(), \"port\": actual_port, \"url\": url });\n        let _ = std::fs::write(state_file(&qdir, &key), json_compact(&st));\n    } else {\n        io.out(&format!(\"QUESTION URL: {}\\n\", url));\n        io.out(\"Waiting for the user to choose in the browser (Ctrl-C aborts)...\\n\");\n    }\n    if !a.has(\"no-open\") {\n        open_system_browser(&url, &env);\n    }\n    let _ = io.stdout.flush();","sourceCodeStart":399,"sourceCodeEnd":435,"githubUrl":"https://github.com/pbakaus/impeccable/blob/2bc2879276c1f321a53c4ca99d3371e411329b52/crates/context/src/serve_question.rs#L399-L435","documentation":"The tiny_http server failed to bind 127.0.0.1 on the requested port. The command reports it as a Node-style `listen EADDRINUSE` error and exits 1. EADDRINUSE means the address/port is already in use by another socket.","triggerScenarios":"`serve-question --port <n>` (or a detached-serve key invocation with an explicit port) where an explicit finite port >= 0 is requested and another process already listens on it. Port 0 (ephemeral) cannot produce this.","commonSituations":"A previous serve-question instance still running (especially detached-serve), another dev server on the same port, or a lingering TIME_WAIT/locked port in containers.","solutions":["Kill the existing process holding the port (`lsof -iTCP:<port> -sTCP:LISTEN`).","Omit the --port flag or pass 0 to let the OS pick a free ephemeral port.","Choose a different explicit port.","If a detached serve is still alive, reuse its URL rather than serving again."],"exampleFix":"// before\nimpeccable serve-question --port 3000 detached-serve payload.json\n// after\nimpeccable serve-question payload.json   // port 0, OS-assigned","handlingStrategy":"fallback","validationCode":"const net = require('net');\nfunction portFree(port) {\n  return new Promise(res => {\n    const s = net.createServer();\n    s.once('error', () => res(false));\n    s.listen(port, '127.0.0.1', () => s.close(() => res(true)));\n  });\n}","typeGuard":null,"tryCatchPattern":"try {\n  run(`impeccable serve-question --port ${port} ...`);\n} catch (e) {\n  if (e.stderr.includes('EADDRINUSE')) return run(`impeccable serve-question ...`); // omit --port\n  throw e;\n}","preventionTips":["Omit --port so the OS assigns an ephemeral port.","Before detached-serve, check for a still-running previous instance.","Use `lsof -iTCP:<port> -sTCP:LISTEN` to find squatters.","In containers, ensure the loopback port is not mapped twice."],"tags":["network","port","server","cli"],"backgroundTag":"address-already-in-use","analyzedSha":"2bc2879276c1f321a53c4ca99d3371e411329b52","analyzedAt":"2026-09-08T04:51:14.109Z","contentChangedAt":"2026-09-08T04:51:14.109Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}