paperclipai/paperclip · error

native_session_multi_run_unavailable

native_session_multi_run_unavailable

Error message

native_session_multi_run_unavailable

What it means

attachRun is an optional capability on a HarnessSession. After identity binding succeeds, the backend checks whether the underlying session implements attachRun; if it is undefined, the session driver does not support multi-run attachment and this error is thrown. It signals a driver capability gap, not a caller mistake in identity.

Source

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

      threadLineage: this.#session.lineage !== undefined,
    };
  }

  async attachRun(input: {
    identity: OpenNativeSessionInput["identity"];
  }): Promise<void> {
    this.#assertProtocolIntegrity();
    const currentIdentity = this.#input.identity;
    if (
      input.identity.sessionId !== currentIdentity.sessionId ||
      input.identity.companyId !== currentIdentity.companyId ||
      input.identity.issueId !== currentIdentity.issueId ||
      input.identity.agentId !== currentIdentity.agentId
    ) {
      throw new Error("native_session_attach_binding_mismatch");
    }
    if (this.#session.attachRun === undefined) {
      throw new Error("native_session_multi_run_unavailable");
    }
    try {
      await this.#session.attachRun({ runId: input.identity.runId });
      this.#assertProtocolIntegrity();
    } catch (error) {
      this.#rethrowProtocolIntegrity(error);
      throw error;
    }
    this.#input = { ...this.#input, identity: structuredClone(input.identity) };
    this.#terminal = null;
    this.#explicitlyCancelled = false;
  }

  async detachControllerForRestart(): Promise<void> {
    if (this.#session.detachControllerForRestart === undefined) return;
    await this.#session.detachControllerForRestart();
  }

View on GitHub (pinned to 01ad858492)

Solutions

1. Check the driver/adapter version and upgrade to one that implements attachRun
2. If the driver is up to date, start a new session per run instead of attaching multiple runs to one session
3. Feature-check before calling: if (session.attachRun === undefined) fall back to a fresh session

Example fix

// before
await backend.attachRun({ identity });
// after
if (!backend.supportsMultiRun()) {
  backend = await createNativeSessionBackend({ identity });
} else {
  await backend.attachRun({ identity });
}

if (backend.supportsMultiRun?.() === false) { startFreshSession(); }

const multiRunSupported = typeof (session as HarnessSession).attachRun === 'function';

try { await backend.attachRun({ identity }); } catch (e) { if (e.message === 'native_session_multi_run_unavailable') { backend = await createNativeSessionBackend({ identity }); } else throw e; }

When it happens

Trigger: Calling attachRun on a native session whose driver only supports a single run per session (session.attachRun === undefined). Typical with harness drivers that lack the multi-run protocol extension.

Common situations: Using an older agent adapter or driver version that predates multi-run support; a driver built before the attachRun protocol method was added; calling attachRun on a backend created from a session factory that never wires attachRun.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• steering is unavailable
• native_runtime_request_resolution_unavailable
• native_session_goal_unavailable
• Codex thread response omitted thread.id
• provider_initialize_protocol_error

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