paperclipai/paperclip · error

HTTPS exposure failed

Error message

HTTPS exposure failed: ${code} — ${provisioned.errorDetail}

What it means

The post-start provisionExposure call failed and returned an error code with detail (e.g. TLS/provisioning backend failure). The runtime service record exists but its HTTPS exposure could not be provisioned, so the start fails with the exposure error code and detail.

Solutions

  1. Read the provisioning error code and errorDetail, fix the exposure configuration accordingly, and retry.
  2. Check exposure provider credentials and network reachability, then retry the HTTPS exposure.
Defensive patterns

Strategy: retry

When it happens

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

Appendix: source

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

    releasePortReservation(reservedPort);
    releasePortReservation(claimedIdentityPort);
    if (record.exposureConfig && record.exposureHandle && record.port) {
      const provisioned = await provisionExposure(workspaceRuntimeExposureDeps, {
        runtimeId: record.id,
        config: record.exposureConfig,
        handle: record.exposureHandle,
        hostname: exposureHostname!,
        appPort: record.port,
      });
      record.exposure = provisioned.status;
      record.exposureHandle = provisioned.handle;
      record.url = provisioned.status.publicUrl;
      await persistRuntimeServiceRecord(record.db, record);
      if (provisioned.status.state !== "ready" || !record.url) {
        // Carry the reason, not just the code: a bare `listener_ownership_mismatch`
        // in the operation log is what made PAP-17254 undiagnosable (PAP-17256).
        const code = provisioned.status.lastError ?? "unknown error";
        throw new Error(
          `HTTPS exposure failed: ${code}${provisioned.errorDetail ? ` — ${provisioned.errorDetail}` : ""}`,
        );
      }
    }
    // Transport readiness only proves a listener answered. A managed workspace
    // must additionally satisfy the protected readiness contract — own database,
    // cloned rows, login handoff, and matching instance/workspace identity —
    // before it may be published as running/healthy (PAP-17572).
    if (managedWorkspaceIdentity) {
      const publishHealthUrl = resolveRuntimeServiceHealthUrl(
        record.port ? `http://127.0.0.1:${record.port}` : rewriteUrlHostToLoopback(record.url ?? backendUrl),
        { serviceName, command },
      );
      if (!publishHealthUrl) {
        throw new Error("Managed workspace readiness gate could not resolve a health URL");
      }
      let gate = await waitForManagedWorkspaceReadiness({
        healthUrl: publishHealthUrl,

View on GitHub (pinned to a7e689b3c3)