biomejs/biome · error · io::Error

ConnectionReset

ConnectionReset

Error message

the server process exited before the connection could be established

What it means

Unix daemon bootstrap failure (crates/biome_cli/src/service/unix.rs:226-235). ensure_daemon retries the socket connection up to 10 times; after spawning the daemon child it waits 50ms via tokio::select - if the child process exits within that window, the CLI returns io::ErrorKind::ConnectionReset with this message. In short: the Biome daemon process was spawned but died before it could listen on its socket (path from get_socket_name(): the biome cache dir plus 'biome-socket-{VERSION}', unix.rs:26-28).

Source

Thrown at crates/biome_cli/src/service/unix.rs:233

                return Ok(current_child.is_some());
            }

            // There's no process listening on the global socket
            Err(err)
                if matches!(
                    err.kind(),
                    ErrorKind::NotFound | ErrorKind::ConnectionRefused
                ) =>
            {
                last_error = Some(err);

                if let Some(current_child) = &mut current_child {
                    // If we have a handle to the daemon process, wait for a few
                    // milliseconds for it to exit, or retry the connection
                    tokio::select! {
                        result = current_child.wait() => {
                            let _status = result?;
                            return Err(io::Error::new(
                                io::ErrorKind::ConnectionReset,
                                "the server process exited before the connection could be established",
                            ));
                        }
                        _ = time::sleep(Duration::from_millis(50)) => {}
                    }
                } else {
                    // Spawn the daemon process and wait a few milliseconds for
                    // it to become ready then retry the connection
                    current_child = Some(spawn_daemon(
                        stop_on_disconnect,
                        watcher_configuration.clone(),
                        log_options.clone(),
                    )?);
                    time::sleep(Duration::from_millis(50)).await;
                }
            }

View on GitHub (pinned to 45a19bbf17)

Solutions

1. Run biome stop (or biome daemon stop) to clean up, then retry; if unavailable, remove the stale socket manually: rm -f "${XDG_CACHE_HOME:-$HOME/.cache}/biome"/biome-socket-*
2. Ensure the cache dir is writable by the current user: mkdir -p "${XDG_CACHE_HOME:-$HOME/.cache}/biome" and check permissions
3. Start the daemon in the foreground (biome start --verbose, or run the daemon binary directly) to see why the child exits - look for startup panics, socket bind errors, or config parse errors
4. Verify the binary: correct architecture, not corrupted mid-download, and CLI/daemon from the same Biome version; re-download if suspect
5. If an environment variable like TMPDIR/XDG_CACHE_HOME points somewhere unusual, set it to a writable directory and retry

Example fix

# before
biome format src/  # error: the server process exited before the connection could be established

# after
biome stop 2>/dev/null || rm -f "${XDG_CACHE_HOME:-$HOME/.cache}/biome"/biome-socket-*
biome start --verbose  # observe daemon startup, then retry the command

# shell - clean stale sockets and verify writability before invoking Biome
CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/biome"
mkdir -p "$CACHE_DIR" || { echo "cannot create cache dir" >&2; exit 1; }
[ -w "$CACHE_DIR" ] || { echo "cache dir not writable" >&2; exit 1; }
rm -f "$CACHE_DIR"/biome-socket-* 2>/dev/null
biome start

# shell - retry once after cleanup, then surface the daemon's own error
biome format src/ || {
  biome stop 2>/dev/null || rm -f "${XDG_CACHE_HOME:-$HOME/.cache}/biome"/biome-socket-*
  biome start --verbose || exit 1   # show why the daemon dies at startup
  biome format src/
}

When it happens

Trigger: Any Biome CLI command needing the daemon (biome start, LSP socket usage, biome __listen_socket) when the freshly spawned daemon process crashes at startup: stale socket file owned by another user, non-writable cache dir (XDG_CACHE_HOME / TMPDIR), incompatible or corrupted binary, or the child exiting due to a startup error.

Common situations: Containers/CI sandboxes with read-only HOME or cache dirs; two Biome versions sharing the machine where the stale socket for this VERSION belongs to a dead process; upgrading Biome while an old daemon lingers; permission mismatch when switching users; disk-full or noexec mount preventing the child from running.

AI-assisted analysis of biomejs/biome@45a19bbf17 (2026-08-20). Data as JSON: /api/errors/4e760193d84a732c. Report an issue: GitHub.