paperclipai/paperclip · error

Runtime service " " could not start because port is already…

Error message

Runtime service "${serviceName}" could not start because port ${conflictPort} is already in use by ${ownerDescription}

What it means

Pre-start checks found the service's fixed port already owned by another local process (pid and its cwd reported). Non-auto ports that cannot be reallocated make the start refuse immediately with the conflicting owner identified.

Solutions

1. Stop the process currently using the port, then retry starting the service.
2. Configure a different port for the service.

When it happens

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

Appendix: source

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

  const conflictPort = reservedExposure ? null : port;
  if (conflictPort) {
    const ownerPid = await readLocalServicePortOwner(conflictPort);
    if (ownerPid) {
      if (canAllocateFixedPort || portType === "auto") {
        throw new RuntimeServicePortBindCollision(conflictPort);
      }
      const ownerCwd = await readLocalServiceProcessCwd(ownerPid);
      const ownerIsInWorkspace = ownerCwd
        ? await isLocalServiceProcessInWorkspace(ownerCwd, serviceCwd)
        : null;
      const ownerDescription = ownerCwd ? `pid ${ownerPid} (cwd: ${ownerCwd})` : `pid ${ownerPid} (cwd unavailable)`;
      releasePortReservation(reservedPort);
      if (ownerIsInWorkspace === false) {
        throw new Error(
          `Runtime service "${serviceName}" could not start because port ${conflictPort} has a cross-workspace port conflict with ${ownerDescription}; requested workspace: ${serviceCwd}. Stop the other service or configure a different port.`,
        );
      }
      throw new Error(
        `Runtime service "${serviceName}" could not start because port ${conflictPort} is already in use by ${ownerDescription}`,
      );
    }
    // A configured port that is free right now can still be taken by a sibling workspace that
    // is mid-start. Claiming it in-process makes the loser fail terminally here instead of
    // silently racing to bind and then hanging on a readiness probe it can never satisfy.
    // `conflictPort !== reservedPort` guards the port this start allocated for itself: we
    // must not fail a start by colliding with our own reservation.
    if (!claimRuntimeServiceBindPort(conflictPort, reservedPort)) {
      releasePortReservation(reservedPort);
      throw new Error(
        `Runtime service "${serviceName}" could not start because configured port ${conflictPort} is already being claimed by another managed start in this instance. Retry once that start settles, or configure a different port.`,
      );
    }
  }
  const claimedIdentityPort = conflictPort && conflictPort !== reservedPort ? conflictPort : null;

  const nowIso = new Date().toISOString();

View on GitHub (pinned to a7e689b3c3)