paperclipai/paperclip · error

Warm run transition requires its exact approved runner artif

Error message

Warm run transition requires its exact approved runner artifact.

What it means

When rehydrating/resuming a control plane with a stored warm transition, the caller must present the exact approved runner artifact the transition receipt recorded. If the supplied expectedRunnerVersion or expectedRunnerDigest differs from transition.receipt, the plane throws rather than resuming under a different binary.

Source

Thrown at packages/paperclip-runner/src/control-plane/durable-prp-control-plane.ts:1500

          options.connectionLeaseTtlMs < 60_000 ||
          options.connectionLeaseTtlMs > 24 * 60 * 60 * 1_000))
    ) {
      throw new Error("Durable PRP control plane options are invalid.");
    }
    this.#identity = structuredClone(options.identity);
    this.#store = new DurableCoreStore(
      options.stateDirectory,
      options.identity,
    );
    this.#expectedRunnerVersion = options.expectedRunnerVersion;
    this.#expectedRunnerDigest = options.expectedRunnerDigest;
    const transition = this.#store.state.warmTransition;
    if (
      transition &&
      (transition.receipt.runnerVersion !== options.expectedRunnerVersion ||
        transition.receipt.runnerDigest !== options.expectedRunnerDigest)
    ) {
      throw new Error(
        "Warm run transition requires its exact approved runner artifact.",
      );
    }
    this.#onSemanticToolInput = options.onSemanticToolInput;
    this.#onCommittedEvent = options.onCommittedEvent;
    this.#beforeAuthenticatedConnection = options.beforeAuthenticatedConnection;
    this.#onProtocolIntegrityError = options.onProtocolIntegrityError;
    this.#connectionLeaseTtlMs = options.connectionLeaseTtlMs ?? 60_000;
  }

  get store(): DurablePrpControlPlaneStore {
    return this.#store;
  }

  getCommand(commandId: string): DurableRecoveryCoreCommand | undefined {
    return (
      this.#store.state.commands.find(
        (command) => command.commandId === commandId,

View on GitHub (pinned to 01ad858492)

Solutions

1. Pass the expectedRunnerVersion/expectedRunnerDigest recorded in state.warmTransition.receipt.
2. If the new runner version is intended, clear/complete the pending warm transition (cold start) instead of warm-resuming.
3. Verify the runner artifact digest (hash the binary) and correct the options values.
4. Re-approve the warm transition for the new artifact if your workflow supports re-approval.

Example fix

// before
resume({ expectedRunnerVersion: '1.2.0', expectedRunnerDigest: 'abc' });
// after
const { receipt } = store.state.warmTransition;
resume({ expectedRunnerVersion: receipt.runnerVersion, expectedRunnerDigest: receipt.runnerDigest });

const t = store.state.warmTransition;
if (t && (options.expectedRunnerVersion !== t.receipt.runnerVersion || options.expectedRunnerDigest !== t.receipt.runnerDigest)) {
  throw new Error('runner artifact does not match approved warm transition; cold start instead');
}

try {
  await controlPlane.resume(options);
} catch (e) {
  if (e.message.includes('exact approved runner artifact')) {
    console.error('runner binary changed since warm transition approval; perform a cold start or re-approve');
    throw e;
  }
  throw e;
}

When it happens

Trigger: Calling the resume/start options with expectedRunnerVersion/expectedRunnerDigest that do not match the receipt stored in state.warmTransition — e.g. the runner was upgraded or rebuilt between shutdown and warm resume.

Common situations: Deploying a new runner version into a workspace with a pending warm transition; rebuilding the binary locally so its digest changed; pointing the resume at a different runner build than the one approved for the warm path.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• OpenCode target executable is not a regular file
• ACPX session is not at a safe suspension point
• OpenCode thread is not open
• Warm run transition binding is invalid.
• Durable authority commit is indeterminate; reload is require

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