paperclipai/paperclip · error · Error

ACPX identity permission mode is invalid

Error message

ACPX identity permission mode is invalid

What it means

validatedRecord re-validates every field of a persisted ACPX identity record parsed from disk. When the permissionMode field is not one of the known permission modes (per isPermissionMode), the record is considered corrupt or foreign and this error is thrown. This happens before any recovery logic runs, so a tampered or version-skewed record never reaches session handling.

Source

Thrown at packages/paperclip-runner/src/drivers/acpx/recovery-identity.ts:233

  if (value.schema !== ACPX_IDENTITY_RECORD_SCHEMA) {
    throw new Error("Unsupported ACPX identity record schema");
  }
  for (const field of [
    "normalizedSessionId",
    "acpxRecordId",
    "backendSessionId",
    "agentSessionId",
    "requestedModel",
    "effectiveModel",
  ] as const) {
    validateIdentity(value[field], field);
  }
  for (const field of ["profileDigest", "workspaceDigest"] as const) {
    if (!isDigest(value[field]))
      throw new Error(`ACPX identity ${field} is invalid`);
  }
  if (!isPermissionMode(value.permissionMode)) {
    throw new Error("ACPX identity permission mode is invalid");
  }
  validateFenceCandidates(value.providerLifetimeFenceCandidates);
  return value as unknown as AcpxIdentityRecord;
}

function validateExpected(expected: AcpxExpectedSessionIdentity): void {
  if (expected.kind !== "acpx") throw new Error("Expected ACPX identity kind");
  for (const value of [
    expected.normalizedSessionId,
    expected.acpxRecordId,
    expected.backendSessionId,
    expected.agentSessionId,
    expected.requestedModel,
    expected.effectiveModel,
  ]) {
    validateIdentity(value, "expected ACPX");
  }
  if (

View on GitHub (pinned to 01ad858492)

Solutions

1. Discard the stale runtime directory/record and start a new session — the record cannot be trusted.
2. Align runner versions: recover the session with the same library version that wrote it.
3. Verify the record file's permissionMode value against the library's accepted permission modes before manual editing.
4. If you must keep the session, re-create the identity record programmatically via createAcpxIdentityRecord with a valid permissionMode.

Example fix

// before
const record = { permissionMode: "yolo" }; // not a known mode
// after
const record = { permissionMode: "default" }; // value accepted by isPermissionMode

const KNOWN_MODES = new Set(["default", "acceptEdits", "bypassAll"]);
const isValidRecord = (v: unknown): v is AcpxIdentityRecord =>
  typeof v === "object" && v !== null && "permissionMode" in v &&
  KNOWN_MODES.has((v as { permissionMode: string }).permissionMode);

try {
  const record = parsePersistedRecord(raw);
} catch (e) {
  if (e.message === "ACPX identity permission mode is invalid") {
    discardRuntimeDirectory(sessionId); // corrupt/foreign record
    return startFreshSession();
  }
  throw e;
}

When it happens

Trigger: Loading a persisted AcpxIdentityRecord whose permissionMode field is missing, null, an unknown string, or a mode introduced by a different/newer version of the library — via parsePersistedRecord() during session recovery.

Common situations: Manual editing or partial truncation of the runtime record file; a newer runner version writing modes an older parser does not know; a corrupted disk state or hand-rolled record in tests.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• persisted Codex ACPX session identity is inconsistent
• Expected ACPX permission mode is invalid
• ACPX provider lifetime fence candidates are invalid
• invalid_provider
• eval-session acpxAgent must be codex or claude

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