paperclipai/paperclip · error

Failed to start runtime service

Error message

Failed to start runtime service "${serviceName}": ${actionableFailure}${serviceOutputExcerpt ? ` | output: ${serviceOutputExcerpt.trim()}` : ""}

What it means

startLocalRuntimeService failed for serviceName: the raw failure was converted into an actionableFailure message with an output excerpt; this is the generic start-failure throw after diagnosis (bind conflicts throw the more specific collision error).

Solutions

1. Read the actionableFailure text and service output excerpt for the root cause
2. Fix the service command/config it names (missing binary, bad env, config path)
3. Address any bind/server.bind conflict described in the diagnosis
4. Retry starting the service after the fix

When it happens

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

Common situations: See trigger scenarios.

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

Appendix: source

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

            + `${exposureCollisionDiagnosis ?? "owner unavailable"}. `
            + `Quarantined pair ${exposureCollisionPorts.join("/")} and reallocating.\n`,
        ).catch(() => undefined);
      }
      throw new RuntimeServicePortBindCollision(port, exposureCollisionDiagnosis, true);
    }
    const deploymentBindConflict = /local_trusted requires server\.bind=loopback/i.test(
      `${failureMessage}\n${serviceOutputExcerpt}`,
    );
    // The guest reported an assigned-port EADDRINUSE, but no host listener owned
    // the port. Explain that the runtime did not quarantine the pair, so a future
    // occurrence needs no diagnostic cycle and the pool stays intact.
    const unverifiedExposureCollision = exposureTextNamesAssignedPort && !exposureHostCollision;
    const actionableFailure = deploymentBindConflict
      ? `${failureMessage} | deployment/bind conflict: local_trusted requires server.bind=loopback; the managed runtime requested an incompatible bind mode`
      : unverifiedExposureCollision
        ? `${failureMessage} | exposure port collision not verified: the guest reported EADDRINUSE on assigned port ${exposureNamedPorts.join("/")}, but no host listener owns it (${exposureCollisionDiagnosis ?? "owner unavailable"}); the runtime did not quarantine the pair`
        : failureMessage;
    throw new Error(
      `Failed to start runtime service "${serviceName}": ${actionableFailure}${serviceOutputExcerpt ? ` | output: ${serviceOutputExcerpt.trim()}` : ""}`,
    );
  });

  return { record, readiness: readinessPromise };
}

async function prepareRuntimeProvisioning(
  input: StartLocalRuntimeServiceInput,
): Promise<RuntimeServiceRecord | null> {
  const runtimeProvisionCommand = asString(input.runtimeProvisionCommand, "").trim();
  if (!runtimeProvisionCommand) return null;
  const coordinator = input.provisionCoordinator ?? createRuntimeProvisionCoordinator();
  if (coordinator.promise) {
    await coordinator.promise;
    return null;
  }

View on GitHub (pinned to a7e689b3c3)