paperclipai/paperclip · error

service process exited before binding its allocated port

Error message

service process exited before binding its allocated port

What it means

waitForAllocatedPortBind detected the spawned service child process exited (exitCode or signalCode set) before it ever bound its allocated port. The service crashed during startup; the bind wait aborts with this cause.

Source

Thrown at server/src/services/workspace-runtime.ts:4812

      lastError = `received HTTP ${response.status}`;
    } catch (err) {
      lastError = err instanceof Error ? err.message : String(err);
    }
    if (now() >= deadline) break;
    await delay(Math.min(intervalMs, Math.max(0, deadline - now())));
  }
  throw new Error(`Readiness check failed for ${readinessUrl}: ${lastError}`);
}

async function waitForAllocatedPortBind(input: {
  service: Record<string, unknown>;
  port: number;
  child: ChildProcess;
}) {
  const deadline = Date.now() + resolveWorkspaceRuntimeReadinessTimeoutSec(input.service) * 1000;
  while (Date.now() < deadline) {
    if (input.child.exitCode !== null || input.child.signalCode !== null) {
      throw new Error("service process exited before binding its allocated port");
    }

    const ownerPid = await readLocalServicePortOwner(input.port);
    if (ownerPid) {
      const childPid = input.child.pid ?? null;
      if (!childPid || !(await isLocalServiceProcessOwnedBy(ownerPid, childPid))) {
        throw new RuntimeServicePortBindCollision(input.port);
      }
      // Require the same launched process group to retain ownership across a stability delay.
      // Cwd matching alone is insufficient because sibling services can share a workspace.
      await delay(250);
      if (input.child.exitCode !== null || input.child.signalCode !== null) {
        throw new Error("service process exited after losing its allocated port");
      }
      const stableOwnerPid = await readLocalServicePortOwner(input.port);
      if (!stableOwnerPid || !(await isLocalServiceProcessOwnedBy(stableOwnerPid, childPid))) {
        throw new RuntimeServicePortBindCollision(input.port);
      }

View on GitHub (pinned to a7e689b3c3)

Solutions

1. Inspect the service's stderr/logs to find why it exited, fix the startup failure, and restart it.
2. Ensure the service binds the allocated port rather than choosing its own or exiting early.

When it happens

Trigger: Thrown at server/src/services/workspace-runtime.ts:4659 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@a7e689b3c3 (2026-08-18). Data as JSON: /api/errors/671bde8b62a8a4f4. Report an issue: GitHub.