paperclipai/paperclip · error

provider_initialize_protocol_error

provider_initialize_protocol_error

Error message

provider_initialize_protocol_error: provider=${provider} stage=${stage} missing durable provider session identity

What it means

assertProviderSessionIdentity enforces that after a provider initialize stage the driver returned a durable identity pair: a non-empty driverSessionId and a non-empty providerSessionId. These IDs are persisted to enable session recovery across process restarts. If either is missing or blank, the protocol contract was violated and the session open/recover fails with a coded protocol error.

Source

Thrown at packages/paperclip-runner/src/backends/harness-driver-backend.ts:384

    }
    if (bytes > maxBytes) return maxBytes + 1;
  }
  return bytes;
}

function assertProviderSessionIdentity(
  session: HarnessSession,
  provider: string,
  stage: "session.open" | "session.recover",
): void {
  const ids = session.ids();
  if (
    typeof ids.driverSessionId !== "string" ||
    ids.driverSessionId.trim().length === 0 ||
    typeof ids.providerSessionId !== "string" ||
    ids.providerSessionId.trim().length === 0
  ) {
    throw new Error(
      `provider_initialize_protocol_error: provider=${provider} stage=${stage} missing durable provider session identity`,
    );
  }
}

class HarnessNativeSession implements NativeSession {
  #input: OpenNativeSessionInput;
  readonly #session: HarnessSession;
  #terminal: PrpTerminalState | null = null;
  #explicitlyCancelled = false;
  #protocolIntegrityFailure: NativeSessionProtocolIntegrityError | null = null;

  #assertProtocolIntegrity(): void {
    if (this.#protocolIntegrityFailure !== null)
      throw this.#protocolIntegrityFailure;
  }

  #rethrowProtocolIntegrity(error: unknown): void {

View on GitHub (pinned to 01ad858492)

Solutions

1. Inspect the driver's initialize/recover response to see which of driverSessionId/providerSessionId is missing and fix the driver to return both.
2. Check for a driver/provider version mismatch and pin or upgrade the driver to one that returns durable session identity.
3. If the provider API changed its response shape, update the driver's response parsing to extract the new session id field.

Example fix

// before (driver returns incomplete ids)
return { ids: { driverSessionId: localId } };
// after
return { ids: { driverSessionId: localId, providerSessionId: response.providerSessionId } };

function hasDurableIdentity(ids) {
  return typeof ids.driverSessionId === "string" && ids.driverSessionId.trim().length > 0 &&
         typeof ids.providerSessionId === "string" && ids.providerSessionId.trim().length > 0;
}

function hasDurableIdentity(ids) {
  return typeof ids?.driverSessionId === "string" && ids.driverSessionId.trim() !== "" &&
         typeof ids?.providerSessionId === "string" && ids.providerSessionId.trim() !== "";
}

try {
  const session = await backend.openSession(input);
} catch (err) {
  if (err.message.includes("provider_initialize_protocol_error") && err.message.includes("missing durable provider session identity")) {
    console.error("Driver did not return durable session ids; check driver version/response parsing");
  }
  throw err;
}

When it happens

Trigger: openSession or recoverSession completes a provider initialize/recover stage, but the driver's ids object has a missing, empty, or whitespace-only driverSessionId or providerSessionId.

Common situations: A driver implementation (or updated driver version) returning only a local session id without the provider's session id; a provider API change that stopped echoing a session identifier; a truncated or malformed initialize response parsed into ids with empty fields.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• provider_initialize_protocol_error
• Refusing an unrecognized local provider smoke root
• Remote runner workspace authority requires a runnerd transpo
• native_session_multi_run_unavailable
• native_runtime_request_resolution_unavailable

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/d3369b0b2eabc134. Report an issue: GitHub.