{"record":{"id":"ac9db6c6268ad526","repo":"pbakaus/impeccable","slug":"serve-question-server-failed-to-start","errorCode":null,"errorMessage":"serve-question: server failed to start{}\n","messagePattern":"serve-question: server failed to start(.+?)\n","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/context/src/serve_question.rs","lineNumber":380,"sourceCode":"            }\n            // JS: spawn(..., { detached: true }) + child.unref()\n            impeccable_common::proc::detach(&mut cmd);\n            cmd.spawn()\n        };\n        let _ = spawned; // detached: never waited on\n        let deadline = now_ms() + 8000.0;\n        while now_ms() < deadline && !exists(&state_file(&qdir, &key)) {\n            sleep_ms(100);\n        }\n        if !exists(&state_file(&qdir, &key)) {\n            let tail = safe_read(&log_file)\n                .map(|t| {\n                    let lines: Vec<&str> = crate::util::js_trim(&t).split('\\n').collect();\n                    let n = lines.len();\n                    lines[n.saturating_sub(4)..].join(\"\\n  \")\n                })\n                .unwrap_or_default();\n            io.err(&format!(\"serve-question: server failed to start{}\\n\", if tail.is_empty() { String::new() } else { format!(\"\\n  {}\", tail) }));\n            let rel = jsp::relative(&cwd, &cwd, &log_file);\n            io.err(&format!(\"serve-question: log at {}. A sandboxed exec that cannot listen on localhost causes exactly this; rerun this command once through the harness's network-enabled or unsandboxed command tool before falling back.\\n\", if rel.is_empty() { log_file.clone() } else { rel }));\n            return 1;\n        }\n        let state = read_state(&qdir, &key).unwrap_or_default();\n        io.out(&format!(\"QUESTION URL: {}\\n\", state.get(\"url\").map(js_str).unwrap_or_default()));\n        io.out(&format!(\"QUESTION KEY: {}\\n\", key));\n        io.out(\"Open the URL for the user now: in-app browser when the harness has one, otherwise the system opener (macOS `open`, Linux `xdg-open`), otherwise show the URL.\\n\");\n        io.out(&format!(\"Then collect the answer with: {} --wait --key {}\\n\", crate::provider::detect(&env, &cwd).verb_cmd(\"serve-question\"), key));\n        return 0;\n    }\n\n    // ---- server (blocking or detached) ----\n    let raw = match &payload_path {\n        Some(pp) => match std::fs::read(jsp::resolve(&cwd, &[pp])) {\n            Ok(b) => String::from_utf8_lossy(&b).into_owned(),\n            Err(e) => {\n                io.err(&format!(\"Error: {}\\n\", crate::util::node_read_error(pp, &e)));","sourceCodeStart":362,"sourceCodeEnd":398,"githubUrl":"https://github.com/pbakaus/impeccable/blob/2bc2879276c1f321a53c4ca99d3371e411329b52/crates/context/src/serve_question.rs#L362-L398","documentation":"The `serve-question` subcommand starts a local HTTP server on 127.0.0.1 to serve a question payload; when that server fails to start, this error prints the last 4 lines of the server log tail (if any) and points at the full log file. It exists so agents/harnesses can diagnose why a localhost listener could not come up. Exit code is 1.","triggerScenarios":"Running `serve-question` when the tiny_http server cannot bind/listen on 127.0.0.1 — typically because the exec is sandboxed without network permissions. The command then reads the log file and prints its tail before returning 1.","commonSituations":"Agent harnesses that sandbox commands with no network access; another process holding the port; firewall or OS restrictions on localhost binds.","solutions":["Rerun the command once through the harness's network-enabled or unsandboxed command tool (as the error itself instructs).","Check the log file mentioned in the follow-up message for the underlying bind failure.","Verify nothing else occupies 127.0.0.1:<port> (or use the default ephemeral port 0).","Check OS/firewall rules allowing listeners on loopback."],"exampleFix":"// before (sandboxed tool)\nimpeccable serve-question payload.json\n// after (run via the harness's network-enabled exec tool)\nexec --network -- impeccable serve-question payload.json","handlingStrategy":"fallback","validationCode":"// shell: confirm the tool can bind loopback before invoking\n(exec 3<>/dev/tcp/127.0.0.1/0) 2>/dev/null && echo loopback-ok || echo sandboxed-no-network","typeGuard":null,"tryCatchPattern":"// wrapper: detect exit 1 and 'failed to start' on stderr, then retry unsandboxed\ntry {\n  run('impeccable serve-question --payload-path q.json');\n} catch (e) {\n  if (/failed to start/.test(e.stderr)) return runUnsandboxed(e.command);\n  throw e;\n}","preventionTips":["Run serve-question only through network-enabled exec tools in harnesses.","Check sandbox network policy before invoking localhost-serving commands.","Keep the log file path from stderr for quick diagnosis.","Prefer ephemeral ports (omit --port) to reduce bind failures."],"tags":["server","network","sandbox","cli"],"backgroundTag":"connection-refused","analyzedSha":"2bc2879276c1f321a53c4ca99d3371e411329b52","analyzedAt":"2026-09-08T04:51:14.109Z","contentChangedAt":"2026-09-08T04:51:14.109Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}