What causes "Timed out waiting for live server to start. " in pbakaus/impeccable?

Re-run the `live` command once — transient startup slowness often resolves on retry.

Timed out waiting for live server to start.

Error message

Timed out waiting for live server to start.

What it means

The `live` command spawns the live server as a detached child via `spawn_detached_with_args`, which waits for the server to come up. If the process cannot be started or does not become ready before the internal deadline, it returns None and the command prints this timeout message and exits 1.

Source

Thrown at crates/live/src/live_server.rs:114

    }

    if argv.iter().any(|a| a == "stop") {
        return stop(&argv, &cwd, io);
    }

    if argv.iter().any(|a| a == "--background") {
        let child_args: Vec<String> = argv
            .iter()
            .filter(|a| *a != "--background")
            .cloned()
            .collect();
        return match crate::server::spawn_detached_with_args(&cwd, &env, &child_args) {
            Some(info) => {
                println(io, &serde_json::to_string(&info).unwrap_or_default());
                0
            }
            None => {
                io.err("Timed out waiting for live server to start.\n");
                1
            }
        };
    }

    // Check for existing session
    if let Some((existing, path)) = read_live_server_info(&cwd, &env) {
        let alive = existing
            .pid
            .map(|p| crate::util::kill0(p).is_ok())
            .unwrap_or(false);
        if alive {
            let port = existing
                .raw
                .get("port")
                .map(js_display)
                .unwrap_or_else(|| "undefined".to_string());
            let pid = existing

View on GitHub (pinned to 2bc2879276)

Solutions

Re-run the `live` command once — transient startup slowness often resolves on retry.
Check for port conflicts or leftover processes (see EADDRINUSE / `live-server stop`) and clear them before starting.
Run the server in the foreground to see the underlying spawn or bind error.

Example fix

// before
$ ./scripts/impeccable live
Timed out waiting for live server to start.
// after
$ <self_cmd> live-server stop   # clear any stale server
$ ./scripts/impeccable live      # retry the start

Defensive patterns

Strategy: retry

Validate before calling

// pre-flight: ensure no stale session and that the launcher is executable before starting
[ ! -f .impeccable/live-server.json ] && [ -x ./scripts/impeccable ] && ./scripts/impeccable live

Try / catch

// on startup timeout, stop any partial server and retry once
try {
  execSync('./scripts/impeccable live', { timeout: 20000 });
} catch (e) {
  if (/Timed out waiting for live server/.test(String(e.stderr))) {
    execSync('<self_cmd> live-server stop || true');
    execSync('./scripts/impeccable live');
  } else throw e;
}

Prevention

Clear stale sessions (`live-server stop`) before starting.
Avoid starting the server on heavily loaded machines without a longer startup budget.
Verify the engine binary can run in the target environment (permissions, sandbox policies).

When it happens

Trigger: Running the `live` command when `crate::server::spawn_detached_with_args(&cwd, &env, &child_args)` returns None — the detached server process failed to bind/respond within the wait window (spawn failure, immediate crash, or slow startup).

Common situations: Another process occupying the port range so the child crashes on bind; a slow machine or loaded CI runner exceeding the readiness timeout; the engine binary unable to spawn (permissions, missing runtime); antivirus/SELinux blocking detached process creation.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of pbakaus/impeccable@2bc2879276 (2026-09-08). Data as JSON: /api/errors/e5aff35caff4fe4b. Report an issue: GitHub.