provider_initialize_protocol_error

provider_initialize_protocol_error

Error message

provider_initialize_protocol_error: provider=${this.#options.driverIdentity?.kind ?? "codex"} stage=session.open omitted provider session identity

What it means

This is the driver's strict session-identity gate: when `requireProviderSessionIdentity` is enabled, the Codex thread response must include a non-empty `sessionId`. Without it Paperclip cannot tie local run records to the provider-side session for resumption and audit. The error is namespaced `provider_initialize_protocol_error` with the driver kind and stage embedded in the message.

Source

Thrown at packages/paperclip-runner/src/drivers/codex/codex-app-server-driver-impl.ts:794

    }
  }

  #openedThread(
    response: Record<string, unknown>,
    initialize: Record<string, unknown>,
    workingDirectory: string,
    collaborationMode: Record<string, unknown> | null,
  ): OpenedCodexThread {
    const thread = record(response.thread);
    const threadId = text(thread.id);
    if (threadId.length === 0)
      throw new Error("Codex thread response omitted thread.id");
    const providerSessionId = text(thread.sessionId) || null;
    if (
      this.#options.requireProviderSessionIdentity &&
      providerSessionId === null
    ) {
      throw new Error(
        `provider_initialize_protocol_error: provider=${this.#options.driverIdentity?.kind ?? "codex"} stage=session.open omitted provider session identity`,
      );
    }
    const activePermissionProfile = record(thread.activePermissionProfile);
    const permissionProfileId = text(activePermissionProfile.id);
    const requestedMode = this.#options.requestedCollaborationMode ?? "default";
    const requiredPermissionProfile =
      text(createSecuredCodexThreadParams(workingDirectory, requestedMode, true, false, this.#options.environment).permissions);
    if (
      permissionProfileId.length > 0 &&
      permissionProfileId !== requiredPermissionProfile
    ) {
      throw new Error(
        "Codex thread did not activate the required filesystem permission profile",
      );
    }
    const configuredPermissionProfile = {
      ...activePermissionProfile,

View on GitHub (pinned to 01ad858492)

Solutions

Upgrade the Codex app-server to a version that returns thread.sessionId
Disable requireProviderSessionIdentity if provider identity is genuinely unavailable and resumption is not needed
Inspect the raw thread/new response to verify whether sessionId is present under a different name and adapt the mapping

Example fix

// before
new CodexAppServerDriver({ requireProviderSessionIdentity: true });
// after (if provider cannot supply sessionId)
new CodexAppServerDriver({ requireProviderSessionIdentity: false });

Defensive patterns

Strategy: validation

Validate before calling

const providerSessionId = typeof thread.sessionId === "string" ? thread.sessionId : "";
const identityRequired = options.requireProviderSessionIdentity ?? true;
if (identityRequired && providerSessionId.length === 0) {
  throw new Error("provider session identity unavailable; upgrade Codex or relax the requirement");
}

Type guard

function hasSessionId(t: unknown): t is { sessionId: string } {
  return typeof t === "object" && t !== null && typeof (t as { sessionId?: unknown }).sessionId === "string" && (t as { sessionId: string }).sessionId.length > 0;
}

Try / catch

try {
  await driver.opened(...);
} catch (err) {
  if (String(err.message).includes("omitted provider session identity")) {
    // check Codex version, or set requireProviderSessionIdentity=false for this provider
  }
  throw err;
}

Prevention

Verify thread.sessionId is present in the provider's thread/new payload before enabling strict identity
Keep the Codex app-server at a version known to report sessionId
Use an integration smoke test that opens a session and asserts identity fields

When it happens

Trigger: Starting a Codex session with `options.requireProviderSessionIdentity === true` while the provider's thread/new response contains `sessionId: null`, an empty string, or omits the field entirely.

Common situations: Upgrading Paperclip to a build that enforces provider session identity while running a Codex version that does not report `thread.sessionId`; self-hosted or proxied app-servers that strip the field; test doubles that only populate thread.id.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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