paperclipai/paperclip · error

Failed to start runtime service "${serviceName}": ${actionab

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).

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)

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.