paperclipai/paperclip · error

ACPX provider identity contains invalid lifetime fences

Error message

ACPX provider identity contains invalid lifetime fences

What it means

parseProviderIdentity requires providerLifetimeFenceCandidates to be an array of exactly 3 distinct integers, each within the inclusive range 49152–65535 (the dynamic/ephemeral port range). These fences are unique lifetime markers for the ACPX provider identity. If the field is missing, not an array, has the wrong length, contains non-integers or out-of-range values, or contains duplicates, the parser throws this error instead of returning an identity.

Source

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

    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 {
    kind: "acpx",
    normalizedSessionId: identity.normalizedSessionId as string,
    acpxRecordId: identity.acpxRecordId as string,
    backendSessionId: identity.backendSessionId as string,
    agentSessionId: identity.agentSessionId as string,
    profileDigest: identity.profileDigest as string,
    workspaceDigest: identity.workspaceDigest as string,
    requestedModel: identity.requestedModel as string,
    effectiveModel: identity.effectiveModel as string,
    ...(permissionMode === undefined ? {} : { permissionMode }),
    providerLifetimeFenceCandidates: fenceCandidates as [
      number,
      number,
      number,
    ],
  };

View on GitHub (pinned to 01ad858492)

Solutions

1. Check the persisted identity's providerLifetimeFenceCandidates and make it an array of exactly 3 distinct integers in [49152, 65535], e.g. [49152, 57344, 65535].
2. Confirm the file was written by a compatible paperclip-runner version; if a format change occurred, migrate the stored record or re-create the session.
3. If the record is unreadable, abandon the persisted session and open a new Codex session so fresh fences are generated.

Example fix

// before
{ "providerLifetimeFenceCandidates": [49152, 49152, 70000] }
// after
{ "providerLifetimeFenceCandidates": [49152, 57344, 65535] }

function hasValidFences(identity) {
  const f = identity?.providerLifetimeFenceCandidates;
  return Array.isArray(f) && f.length === 3 &&
    f.every((n) => Number.isInteger(n) && n >= 49152 && n <= 65535) &&
    new Set(f).size === 3;
}
if (!hasValidFences(storedIdentity)) {
  throw new Error("stored identity has invalid lifetime fences");
}

function isValidFenceArray(v: unknown): v is [number, number, number] {
  return Array.isArray(v) && v.length === 3 &&
    v.every((n) => Number.isInteger(n) && n >= 49_152 && n <= 65_535) &&
    new Set(v).size === 3;
}

When it happens

Trigger: Calling parseProviderIdentity with an ACPX-kind identity whose providerLifetimeFenceCandidates is absent, has fewer/more than 3 entries, contains values below 49152 or above 65535, contains non-integer values (floats, strings, null), or repeats a value so the Set size is not 3.

Common situations: Corrupted or truncated persistence files; older driver versions that stored a different fence format; manual edits that introduced duplicate or out-of-range fence values; JSON round-trips that coerced integers to strings or floats.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• ACPX provider identity contains an invalid permission mode
• 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/ddda183a7a6ab71a. Report an issue: GitHub.