paperclipai/paperclip · error

native_runner_authority_rotation_seed_unavailable

native_runner_authority_rotation_seed_unavailable

Error message

native_runner_authority_rotation_seed_unavailable

What it means

rotatedRunAttachPayload needs a seed run-attach/prepare payload (provider configuration) to retarget onto the new epoch. It looks for a persisted template and a command seed; if neither contains a provider field, there is no basis for constructing the rotated attach payload, so it throws this error. Without the seed, the library refuses to fabricate runner configuration.

Source

Thrown at packages/paperclip-runner/src/live/runnerd-codex-transport.ts:437

  const commands = Array.isArray(state.commands)
    ? state.commands.map(record)
    : [];
  const persistedTemplate =
    state.runAttachTemplate !== null &&
    typeof state.runAttachTemplate === "object" &&
    !Array.isArray(state.runAttachTemplate)
      ? (state.runAttachTemplate as Record<string, unknown>)
      : null;
  const commandSeed = [...commands]
    .reverse()
    .find(
      (command) =>
        (command.type === "run.prepare" || command.type === "run.attach") &&
        record(command.payload).provider !== undefined,
    );
  const seed = persistedTemplate ?? record(commandSeed?.payload);
  if (seed.provider === undefined)
    throw new Error("native_runner_authority_rotation_seed_unavailable");
  return retargetRunAttachPayload(
    seed,
    desired,
    authorizedTools,
    completionContract,
  );
}

function retargetRunAttachPayload(
  seedPayload: Record<string, unknown>,
  desired: DurableRecoveryIdentity,
  authorizedTools: Record<string, unknown> | null,
  completionContract:
    { revision: string; criterionIds: readonly string[] } | undefined,
): Record<string, unknown> {
  const payload = structuredClone(seedPayload);
  const provider = record(payload.provider);
  if (provider.kind === "acpx" || provider.provider === "acpx") {

View on GitHub (pinned to 01ad858492)

Solutions

1. Ensure a run.prepare/run.attach command with a provider payload was recorded before attempting rotation
2. Restore the persisted template or command seed from backup or from the archived control-plane state
3. Re-create the runner session from scratch if no durable seed ever existed (rotation is not applicable)
4. Verify the command-log filter conditions (type run.prepare/run.attach, provider defined) are not excluding your stored commands due to version changes

Example fix

// before
const payload = rotatedRunAttachPayload(...); // throws when no seed provider
// after
const seed = findRunAttachSeed(commands);
if (!seed || seed.payload.provider === undefined) {
  throw new SkipRotationError("no attach seed; resume without epoch rotation");
}
const payload = rotatedRunAttachPayload(...);

const seed = persistedTemplate ?? record(commandSeed?.payload);
if (seed?.provider === undefined) {
  throw new Error("no run.prepare/run.attach seed with provider persisted; rotation unavailable");
}

const hasAttachSeed = (cmd?: { type: string; payload: unknown }) =>
  cmd != null && (cmd.type === "run.prepare" || cmd.type === "run.attach") &&
  typeof cmd.payload === "object" && cmd.payload !== null &&
  (cmd.payload as Record<string, unknown>).provider !== undefined;

try {
  payload = rotatedRunAttachPayload(...);
} catch (err) {
  if ((err as Error).message === "native_runner_authority_rotation_seed_unavailable") {
    return resumeWithoutRotation(); // re-create session instead
  } else throw err;
}

When it happens

Trigger: Calling rotatedRunAttachPayload (via runAttachTemplate) when no persisted template exists and no run.prepare/run.attach command in the seed has a defined provider field — e.g., rotation is attempted before the runner ever persisted its attach configuration.

Common situations: Resuming a runner whose initial run.prepare command was never durably recorded; a data root where control-plane state was archived/removed before the template was written; invoking authority rotation on a freshly created session with no prior attach command; truncation or corruption of the command log.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

• Installing or updating Paperclip requires Node.js ${MINIMUM_
• Paperclip returned no result while ${action}.
• No available loopback port found at or above ${preferredPort
• OpenCode evals require exact version 1.18.17; received ${ver
• devUiUrl must use http or https protocol

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