fix(adapter-node): skip socket cleanup for cluster workers

[tsushanth]

Fixes #16230.

Root cause

The stale-socket cleanup added in #15449 (released in adapter-node 5.5.7) unconditionally runs on every process startup:

if (fs.statSync(path).size === 0) {
  await rm(path);
}

The size === 0 heuristic is meant to detect a stale socket left over from an unclean shutdown, but a live unix domain socket also reports size = 0. In Node cluster / PM2 cluster mode:

1. The primary process binds and creates the socket file.
2. Each worker process inherits the primary's listening handle (no bind() of its own), runs the same startup code, finds size === 0, and deletes the live socket file.
3. Workers appear healthy (they share the in-kernel listening state), but the socket path is gone from disk — the reverse proxy (e.g. nginx proxy_pass unix:…) can no longer connect. No error, no restart, silent regression.

Fix

Import node:cluster and skip the rm() call when the current process is a cluster worker. Workers inherit the socket handle from the primary and must never manage the socket file. The primary (or any single-process deployment) retains the existing cleanup behaviour unchanged.

cluster.isWorker is false in non-cluster processes, so this change is a no-op for single-process deployments.

[pkg-svelte-dev]

Install the latest version of @sveltejs/kit from 4a54700:

pnpm add https://pkg.svelte.dev/@sveltejs/kit/c/4a54700cbf8eb3dc282a9f79e31b192c74ef6fb3

Open in pkg.svelte.dev: https://pkg.svelte.dev/repos/kit/pr/16241

Note

This PR is from a fork. A maintainer must approve approve each commit before it can be built and installed.

[changeset-bot]

🦋 Changeset detected

Latest commit: 4a54700

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages

Name	Type
@sveltejs/adapter-node	Patch
@sveltejs/kit	Major
@sveltejs/adapter-cloudflare	Major
@sveltejs/adapter-vercel	Major
@sveltejs/adapter-auto	Patch
@sveltejs/adapter-static	Patch
@sveltejs/adapter-netlify	Major
@sveltejs/package	Major
@sveltejs/enhanced-img	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[enda]

Thanks for tackling this! The cluster.isWorker guard does fix the regression (workers must never touch the socket file), but I believe it quietly reintroduces the problem #15449 was solving, for the very setups it targeted.

In PM2 cluster mode (and any node:cluster-based supervisor), the primary is the supervisor's own daemon, it never runs the adapter's entry point. Every process that executes index.js has cluster.isWorker === true, so with this guard the stale-socket cleanup never runs at all in cluster deployments. After an unclean shutdown or reboot leaves a stale socket file behind, the bind fails with EADDRINUSE again, exactly the scenario #15449 addressed, where supervisors like PM2 were explicitly mentioned.

The root issue is that statSync(path).size === 0 can't distinguish a stale socket from a live one, both report size 0. Instead of special-casing cluster workers, I'd suggest replacing the heuristic with a liveness probe, which is topology-independent:

1. stat the path; if it doesn't exist or !stats.isSocket(), do nothing (this also avoids ever deleting a regular file, which the size check doesn't guarantee).
2. Try net.connect(path):

• ECONNREFUSED → nothing is listening → stale → safe to remove;
• connection succeeds, any other error, or a short timeout → assume live → leave it alone.

Note the conservative bias: a timeout or an unexpected error never leads to deletion, so the worst remaining case (a bound-but-frozen server) falls back to the old EADDRINUSE, never a silent deletion.

One caveat worth handling: with several instances racing a cold start, there's a TOCTOU window between the probe verdict and the rm: instance A can get ECONNREFUSED on the stale socket, and before its rm runs, instance B removes the stale file and re-binds a fresh live socket at the same path, which A then deletes. This is made worse in cluster mode: a subsequent listen from A would silently reuse the primary's existing handle without recreating the file, so the app keeps running with no socket on disk. Pinning the inode (stat before the probe, re-stat and compare dev+ino right before rm) shrinks that window from milliseconds to a couple of syscalls; an atomic mkdir(path + '.lock') mutex would close it entirely if we want to be strict. A post-listen existsSync(path) check that fails loudly (so the supervisor restarts into a now-free path) is a cheap extra safety net.

Sketch:

import net from 'node:net';
import { rm } from 'node:fs/promises';

function probe(path) {
  return new Promise((resolve) => {
    const socket = net.connect(path);
    const timer = setTimeout(() => {
      socket.destroy();
      resolve(true); // unresponsive but bound, be conservative
    }, 1000);
    socket.once('connect', () => {
      clearTimeout(timer);
      socket.destroy();
      resolve(true);
    });
    socket.once('error', (err) => {
      clearTimeout(timer);
      resolve(err.code !== 'ECONNREFUSED');
    });
  });
}

async function remove_stale_socket(path) {
  let before;
  try {
    before = fs.statSync(path);
  } catch {
    return; // nothing there
  }
  if (!before.isSocket()) return; // not a socket, don't touch it

  const alive = await probe(path);
  if (alive) return;

  try {
    const now = fs.statSync(path);
    if (now.ino !== before.ino || now.dev !== before.dev || !now.isSocket()) {
      return; // replaced since we probed, another instance just bound here
    }
    await rm(path, { force: true });
  } catch {
    // ENOENT: another instance already cleaned up
  }
}

With the probe in place the isWorker guard becomes unnecessary, and keeping it would still leave PM2 cluster mode without any stale-socket cleanup.

Happy to test any build against our PM2-cluster + nginx + unix-socket setup, since that's where we hit the original outage.

[tsushanth]

The Node 20 CI failure is in remote-functions > renders correct values (expected "Example text", received "Updated text") — unrelated to this PR's adapter-node cluster socket change. The same test passes on Node 18, 22, and 24. All adapter-node-specific checks pass. Happy to rebase if there's a known fix upstream, but the failure doesn't appear to be caused by this change.

[tsushanth]

Thanks @enda — great analysis. Replaced the cluster.isWorker guard with a liveness probe as suggested.

What changed:

• Added remove_stale_socket(path) which stats the path (must exist and be a socket), probes with net.connect(), and only removes on ECONNREFUSED. Any other outcome (connect succeeds, timeout after 1s, unexpected error) leaves the file alone.
• Re-stats and compares ino + dev right before rm to close the TOCTOU window between probe and delete.
• Removed the cluster.isWorker guard — no longer needed and blocked cleanup in PM2 cluster setups.
• Dropped the import cluster from 'node:cluster' that was only there for the guard.

The net import was already in scope (Node built-in). No new deps.

[tsushanth]

Reopening — you're right that this is still live, and I shouldn't have auto-closed a thread with active review engagement. The liveness-probe fix from the last commit should be safe for the PM2 cluster-mode case you're describing (it stats+probes the socket rather than trusting cluster.isWorker), but let me know if your repro still trips it and I'll dig further.