paperclip_runner_codex_permission_mode_unqualified

paperclip_runner_codex_permission_mode_unqualified

Error message

paperclip_runner_codex_permission_mode_unqualified: set codexPermissionMode to never before starting or recovering this native run

What it means

For Codex providers, the backend requires approvalPolicy to be 'never' (or unset) because native runs must run fully non-interactive without permission prompts. If a Codex provider is configured with any other approval policy (e.g. 'on-request', 'on-failure', 'untrusted'), the backend refuses to start so the run cannot hang waiting for interactive approvals.

Source

Thrown at packages/paperclip-runner/src/backends/codex-native-backend.ts:124

    options.workingDirectoryAuthority === "remote_runner" &&
    !options.transportFactory
  ) {
    throw new Error(
      "Remote runner workspace authority requires a runnerd transport",
    );
  }
  const driverIdentity = transportDriverIdentity(input);
  const isCodex = input.provider.kind === "codex";
  const supportsCollaborativePlanning =
    isCodex ||
    input.provider.kind === "opencode" ||
    input.provider.kind === "acpx";
  if (
    input.provider.kind === "codex" &&
    input.provider.approvalPolicy !== undefined &&
    input.provider.approvalPolicy !== "never"
  ) {
    throw new Error(
      "paperclip_runner_codex_permission_mode_unqualified: set codexPermissionMode to never before starting or recovering this native run",
    );
  }

  return new HarnessDriverBackend(
    new CodexAppServerDriver({
      ...(input.provider.model ? { model: input.provider.model } : {}),
      // Runnerd owns provider permissions for non-Codex facades. Their
      // Codex-compatible surface must never open a second approval channel.
      approvalPolicy:
        input.provider.kind === "codex"
          ? (input.provider.approvalPolicy ?? "never")
          : "never",
      baseInstructions: nativeSystemInstructions(input),
      includeSkillInstructions: isCodex && "runtimeContext" in input,
      requestedCollaborationMode:
        supportsCollaborativePlanning && "executionMode" in input
          ? input.executionMode

View on GitHub (pinned to 01ad858492)

Solutions

Set codexPermissionMode (approvalPolicy) to 'never' in the provider configuration before starting or recovering the run.
Remove the approvalPolicy field entirely to accept the backend default.
For recovery failures, correct the stored provider options in the run record, then retry recovery.

Example fix

// before
{ provider: { kind: "codex", approvalPolicy: "on-request" } }
// after
{ provider: { kind: "codex", approvalPolicy: "never" } }

Defensive patterns

Strategy: validation

Validate before calling

if (provider.kind === "codex" && provider.approvalPolicy !== undefined && provider.approvalPolicy !== "never") {
  throw new Error(`codexPermissionMode must be 'never', got '${provider.approvalPolicy}'`);
}

Type guard

function codexPolicyIsValid(p) {
  return p.kind !== "codex" || p.approvalPolicy === undefined || p.approvalPolicy === "never";
}

Try / catch

try {
  await backend.openSession(input);
} catch (err) {
  if (err.message.includes("codex_permission_mode_unqualified")) {
    console.error("Set codexPermissionMode to 'never' and restart the run");
    process.exit(1);
  }
  throw err;
}

Prevention

Default codex provider configs to approvalPolicy 'never' for non-interactive runner contexts.
Validate provider options against the backend contract before persisting run records so recovery never inherits an invalid policy.

When it happens

Trigger: Starting or recovering a native Codex run where input.provider.approvalPolicy is defined and not 'never'.

Common situations: Configuring codexPermissionMode from a user default like 'on-request'; migrating an old run record whose stored approval policy predates the 'never' requirement; copying driver options from interactive Codex CLI usage into the runner backend.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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