{"record":{"id":"7aec51b02fed2dbb","repo":"paperclipai/paperclip","slug":"runtime-service-could-not-bind-allocated-port-po-7aec51","errorCode":null,"errorMessage":"Runtime service could not bind allocated port ${port} (${diagnosis})","messagePattern":"Runtime service could not bind allocated port (.+?) \\((.+?)\\)","errorType":"exception","errorClass":"RuntimeServicePortBindCollision","httpStatus":null,"severity":"error","filePath":"server/src/services/workspace-runtime.ts","lineNumber":6163,"sourceCode":"    if (bindCollision && port) throw new RuntimeServicePortBindCollision(port);\n    if (exposureHostCollision && port) {\n      // A verified host listener holds the assigned exposure port. Quarantine the\n      // pair so the bounded re-allocation never re-offers it, then throw a retryable\n      // collision. `startLocalRuntimeService` re-runs allocation, which skips the\n      // quarantined pair and takes the next free pair inside the dedicated range.\n      // This hardens a real host that races an external process for a range port.\n      for (const collisionPort of exposureCollisionPorts) {\n        quarantinedRuntimeExposurePorts.add(collisionPort);\n      }\n      if (input.onLog) {\n        await input.onLog(\n          \"stderr\",\n          `[service:${serviceName}] exposure port ${port} collided during startup (EADDRINUSE); `\n            + `${exposureCollisionDiagnosis ?? \"owner unavailable\"}. `\n            + `Quarantined pair ${exposureCollisionPorts.join(\"/\")} and reallocating.\\n`,\n        ).catch(() => undefined);\n      }\n      throw new RuntimeServicePortBindCollision(port, exposureCollisionDiagnosis, true);\n    }\n    const deploymentBindConflict = /local_trusted requires server\\.bind=loopback/i.test(\n      `${failureMessage}\\n${serviceOutputExcerpt}`,\n    );\n    // The guest reported an assigned-port EADDRINUSE, but no host listener owned\n    // the port. Explain that the runtime did not quarantine the pair, so a future\n    // occurrence needs no diagnostic cycle and the pool stays intact.\n    const unverifiedExposureCollision = exposureTextNamesAssignedPort && !exposureHostCollision;\n    const actionableFailure = deploymentBindConflict\n      ? `${failureMessage} | deployment/bind conflict: local_trusted requires server.bind=loopback; the managed runtime requested an incompatible bind mode`\n      : unverifiedExposureCollision\n        ? `${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`\n        : failureMessage;\n    throw new Error(\n      `Failed to start runtime service \"${serviceName}\": ${actionableFailure}${serviceOutputExcerpt ? ` | output: ${serviceOutputExcerpt.trim()}` : \"\"}`,\n    );\n  });\n","sourceCodeStart":6145,"sourceCodeEnd":6181,"githubUrl":"https://github.com/paperclipai/paperclip/blob/a7e689b3c35347b529cb9f54c9b9a8575a3dcab6/server/src/services/workspace-runtime.ts#L6145-L6181","documentation":"The runtime service reported EADDRINUSE-class bind failure on its allocated port, diagnosed as a bind collision; startLocalRuntimeService re-runs allocation skipping quarantined port pairs, and the collision is thrown as a retryable error.","triggerScenarios":"Thrown at server/src/services/workspace-runtime.ts:6163 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Let the bounded re-allocation retry pick the next free port pair","Free the collided port or stop the external process holding it","Check the quarantine list is not exhausted for the dedicated port range","Inspect the bind diagnosis in the error for owner information"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"a7e689b3c35347b529cb9f54c9b9a8575a3dcab6","analyzedAt":"2026-08-21T17:58:32.592Z","contentChangedAt":"2026-08-21T17:58:32.592Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}