paperclipai/paperclip · error

ACPX provider identity contains an invalid permission mode

Error message

ACPX provider identity contains an invalid permission mode

What it means

parseProviderIdentity validates a persisted ACPX provider-identity record when reconstructing a Codex harness session. The optional permissionMode field must be one of exactly three enumerated strings: "approve-all", "approve-reads", or "deny-all" (or undefined). If it is set to any other value — meaning the stored identity was hand-edited, written by a different driver version, or corrupted — the parser refuses to rebuild the session and throws this error.

Source

Thrown at packages/paperclip-runner/src/drivers/codex/codex-driver-values.ts:72

  ] as const;
  if (
    requiredStrings.some(
      (key) =>
        typeof identity[key] !== "string" ||
        identity[key].length === 0 ||
        identity[key].length > 240,
    )
  ) {
    throw new Error("ACPX provider identity is incomplete");
  }
  const permissionMode = identity.permissionMode;
  if (
    permissionMode !== undefined &&
    permissionMode !== "approve-all" &&
    permissionMode !== "approve-reads" &&
    permissionMode !== "deny-all"
  ) {
    throw new Error(
      "ACPX provider identity contains an invalid permission mode",
    );
  }
  const fenceCandidates = identity.providerLifetimeFenceCandidates;
  if (
    !Array.isArray(fenceCandidates) ||
    fenceCandidates.length !== 3 ||
    fenceCandidates.some(
      (candidate) =>
        !Number.isInteger(candidate) ||
        candidate < 49_152 ||
        candidate > 65_535,
    ) ||
    new Set(fenceCandidates).size !== 3
  ) {
    throw new Error("ACPX provider identity contains invalid lifetime fences");
  }
  return {

View on GitHub (pinned to 01ad858492)

Solutions

1. Inspect the persisted provider identity record and set permissionMode to one of "approve-all", "approve-reads", or "deny-all", or delete the field entirely (undefined is allowed).
2. Verify which Paperclip/paperclip-runner version wrote the record; if a version change renamed enum values, re-run session recovery with matching versions or migrate the persisted field.
3. If the identity record is corrupted beyond repair, discard the persisted session and start a fresh Codex session so a new identity is written with a valid mode.

Example fix

// before (persisted identity)
{ "kind": "acpx", "permissionMode": "approve-writes", ... }
// after
{ "kind": "acpx", "permissionMode": "approve-reads", ... }

const VALID_MODES = ["approve-all", "approve-reads", "deny-all"];
function hasValidPermissionMode(identity) {
  const m = identity?.permissionMode;
  return m === undefined || VALID_MODES.includes(m);
}
if (!hasValidPermissionMode(storedIdentity)) {
  throw new Error("stored identity has invalid permissionMode");
}

function isValidPermissionMode(v: unknown): v is "approve-all" | "approve-reads" | "deny-all" | undefined {
  return v === undefined || v === "approve-all" || v === "approve-reads" || v === "deny-all";
}

When it happens

Trigger: Calling parseProviderIdentity (usually indirectly via providerIdentity during session recovery/rehydration) with a persisted identity object whose kind is "acpx" but whose permissionMode is a non-enumerated string (e.g. "approve-writes", "yolo", "default", or an empty string), a number, or null.

Common situations: Hand-editing session persistence files (e.g. changing sandbox/approval settings manually); running a newer or older build that wrote an extra or renamed permission mode; a schema migration that renamed enum values; JSON corruption that mangled the field.

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

• ACPX provider identity contains invalid lifetime fences
• codex_startup_trust_requires_absolute_paths
• codex_startup_trust_invalid_projects
• codex_startup_trust_invalid_project
• ${label} is not a regular file at ${canonical}.

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