Xvfb on ${display} never became reachable within 3s timeout

Error message

Xvfb on ${display} never became reachable within 3s timeout

What it means

Error "Xvfb on ${display} never became reachable within 3s timeout" thrown in garrytan/gstack.

Source

Thrown at browse/src/xvfb.ts:155

    stdio: ['ignore', 'ignore', 'ignore'],
  });
  proc.unref();

  // Wait for the X server to become reachable — Xvfb takes a few hundred ms
  // to bind. Probe via xdpyinfo with retries.
  const deadline = Date.now() + 3000;
  let ready = false;
  while (Date.now() < deadline) {
    await Bun.sleep(100);
    if (!isDisplayFree(displayNum)) { ready = true; break; }
    // If Xvfb crashed during startup, fail fast.
    if (proc.exitCode != null) {
      throw new Error(`Xvfb on ${display} exited during startup (code ${proc.exitCode}). Hint: install xvfb (apt-get install xvfb / yum install xorg-x11-server-Xvfb).`);
    }
  }
  if (!ready) {
    try { proc.kill('SIGKILL'); } catch { /* ignore */ }
    throw new Error(`Xvfb on ${display} never became reachable within 3s timeout`);
  }

  const startTime = readPidStartTime(proc.pid);
  return {
    pid: proc.pid,
    startTime,
    display,
    close: () => cleanupXvfb({ pid: proc.pid, startTime, display }),
  };
}

/**
 * Cleanup an Xvfb child if it's still ours. Validates ownership first; if
 * the PID has been recycled or the cmdline doesn't match, leave it alone.
 *
 * Best-effort: never throws.
 */
export function cleanupXvfb(state: { pid: number; startTime: string; display: string }): void {

View on GitHub (pinned to 94993f7401)

When it happens

Trigger: Thrown at browse/src/xvfb.ts:155 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

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

AI-assisted analysis of garrytan/gstack@94993f7401 (2026-08-12). Data as JSON: /api/errors/17b996b1abe0786a. Report an issue: GitHub.