paperclipai/paperclip · error

Runtime service did not bind allocated port ${input.port} be

Error message

Runtime service did not bind allocated port ${input.port} before timeout

What it means

The allocated-port bind wait loop reached its deadline without the child owning a stable listener on the port. The presence-based retry exhausted the readiness timeout, so the service start fails with this timeout error.

Source

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

      return;
    }

    // A present listener proves only that some listener appeared. If listener ownership cannot
    // be attributed to this child after a stability delay, retry instead of accepting a sibling.
    // The presence read never binds the port, so it cannot steal the port from the child.
    if (await hasLoopbackPortListener(input.port)) {
      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);
      const childPid = input.child.pid ?? null;
      if (stableOwnerPid && childPid && await isLocalServiceProcessOwnedBy(stableOwnerPid, childPid)) return;
      throw new RuntimeServicePortBindCollision(input.port);
    }
    await delay(50);
  }
  throw new Error(`Runtime service did not bind allocated port ${input.port} before timeout`);
}

function isPaperclipDevRuntimeService(input: { serviceName?: string | null; command?: string | null }) {
  const serviceName = (input.serviceName ?? "").trim().toLowerCase();
  const command = (input.command ?? "").trim().toLowerCase();
  return (
    serviceName === "paperclip-dev"
    || serviceName === "paperclip-dev-once"
    || (command.includes("dev:once") && command.includes("tailscale-auth"))
  );
}

function resolveRuntimeServiceHealthUrl(
  url: string | null,
  input?: { serviceName?: string | null; command?: string | null },
) {
  if (!url || !isPaperclipDevRuntimeService(input ?? {})) return url;
  try {

View on GitHub (pinned to a7e689b3c3)

Solutions

1. Verify the service is actually listening on the expected port (e.g. with ss/lsof) and fix its bind configuration.
2. Increase the bind timeout if the service starts slowly.

When it happens

Trigger: Thrown at server/src/services/workspace-runtime.ts:4695 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 paperclipai/paperclip@a7e689b3c3 (2026-08-18). Data as JSON: /api/errors/4863e811b42705f6. Report an issue: GitHub.