paperclipai/paperclip · error

Could not allocate a free loopback port for a managed runtim

Error message

Could not allocate a free loopback port for a managed runtime service after ${PORT_ALLOCATION_ATTEMPTS} attempts (last candidate ${lastCandidate}).

What it means

allocateRuntimeServicePort probed candidates for a free loopback port but every one of the PORT_ALLOCATION_ATTEMPTS candidates was owned by another local process. Port exhaustion or heavy port churn on the host prevents starting the managed service.

Source

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

 * live process owns. Callers must {@link releasePortReservation} once the service either
 * reached a terminal state or bound the port itself.
 */
export async function allocateRuntimeServicePort(overrides?: {
  probe?: () => Promise<number>;
  portOwnerLookup?: (port: number) => Promise<number | null>;
}): Promise<number> {
  const probe = overrides?.probe ?? probeEphemeralPort;
  const portOwnerLookup = overrides?.portOwnerLookup ?? readLocalServicePortOwner;
  let lastCandidate: number | null = null;
  for (let attempt = 0; attempt < PORT_ALLOCATION_ATTEMPTS; attempt += 1) {
    const candidate = await probe();
    lastCandidate = candidate;
    if (!reservePortIfFree(candidate)) continue;
    const ownerPid = await portOwnerLookup(candidate);
    if (!ownerPid) return candidate;
    releasePortReservation(candidate);
  }
  throw new Error(
    `Could not allocate a free loopback port for a managed runtime service after ${PORT_ALLOCATION_ATTEMPTS} attempts`
      + `${lastCandidate ? ` (last candidate ${lastCandidate})` : ""}.`,
  );
}

function buildTemplateData(input: {
  workspace: RealizedExecutionWorkspace;
  agent: ExecutionWorkspaceAgentRef;
  issue: ExecutionWorkspaceIssueRef | null;
  adapterEnv: Record<string, string>;
  port: number | null;
}) {
  return {
    workspace: {
      cwd: input.workspace.cwd,
      branchName: input.workspace.branchName ?? "",
      worktreePath: input.workspace.worktreePath ?? "",
      repoUrl: input.workspace.repoUrl ?? "",

View on GitHub (pinned to a7e689b3c3)

Solutions

1. Free up loopback ports used by other managed runtime services, then retry the start.
2. Configure an explicit free port for the service instead of relying on automatic allocation.

When it happens

Trigger: Thrown at server/src/services/workspace-runtime.ts:4366 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/3d469e577b2e5975. Report an issue: GitHub.