paperclipai/paperclip · error

Runtime service "${serviceName}" could not start because por

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.

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)

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.