paperclipai/paperclip · error · PaperclipRunnerProviderProfileError

paperclip_runner_codex_permission_mode_unqualified

paperclip_runner_codex_permission_mode_unqualified

Error message

Paperclip Runner currently supports Codex only with codexPermissionMode set to never. Update the agent configuration before starting a new native run.

What it means

resolvePaperclipRunnerProviderProfile calls assertPermissionMode to validate the agent's configured permission mode for a provider. For Codex, only the "never" permission mode is qualified for Paperclip Runner; if codexPermissionMode is set to any other recognized-but-unsupported value, a PaperclipRunnerProviderProfileError with code paperclip_runner_codex_permission_mode_unqualified is thrown before the native run starts.

Source

Thrown at server/src/services/native-runtime/provider-profile.ts:184

      `${label} must be an integer between 1 and ${maximum}.`,
    );
  }
  return value;
}

function assertPermissionMode(
  provider: PaperclipRunnerProvider,
  config: Record<string, unknown>,
): void {
  const capability = PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES[provider];
  if (!capability.configurable) return;
  const configured = config[capability.configKey];
  if (
    configured !== undefined
    && resolvePaperclipRunnerPermissionMode(provider, configured) !== configured
  ) {
    if (provider === "codex") {
      throw new PaperclipRunnerProviderProfileError(
        "paperclip_runner_codex_permission_mode_unqualified",
        "Paperclip Runner currently supports Codex only with codexPermissionMode set to never. Update the agent configuration before starting a new native run.",
      );
    }
    throw new PaperclipRunnerProviderProfileError(
      "runner_permission_mode_invalid",
      `${capability.configKey} is not supported by ${provider}.`,
    );
  }
}

/**
 * Rebind a persisted Claude Managed run only to the still-qualified profile
 * and the profile's current company secret. The secret itself may rotate, but
 * the agent configuration must rotate its binding to the same profile-owned
 * secret before recovery can continue.
 */
export function assertManagedProfileRecoveryBinding(input: {

View on GitHub (pinned to 01ad858492)

Solutions

Edit the agent configuration and set codexPermissionMode to "never".
Start a new native run after the config change (existing runs must be restarted).
If the mode must be non-"never", use a non-Codex provider or a non-runner execution path that supports that mode.

Example fix

// before (agent config)
{ "provider": "codex", "codexPermissionMode": "on-failure" }
// after
{ "provider": "codex", "codexPermissionMode": "never" }

Defensive patterns

Strategy: validation

Validate before calling

if (agent.provider === "codex" && agent.codexPermissionMode !== undefined && agent.codexPermissionMode !== "never") {
  throw new Error("codexPermissionMode must be 'never' for Paperclip Runner");
}

Type guard

function isRunnerQualifiedCodexMode(mode: unknown): mode is "never" { return mode === "never"; }

Try / catch

try {
  const profile = resolvePaperclipRunnerProviderProfile(config);
} catch (err) {
  if (err instanceof PaperclipRunnerProviderProfileError && err.code === "paperclip_runner_codex_permission_mode_unqualified") {
    // prompt the user to set codexPermissionMode: "never" in agent settings
  } else throw err;
}

Prevention

Restrict the agent settings UI for Codex runner agents to the single qualified mode (never).
Validate agent config at save time, not only at run start.
When copying agent configs from other integrations, strip permission modes not qualified for runner use.

When it happens

Trigger: Starting a native run whose agent config has codexPermissionMode set to a value that is a valid Codex mode but not "never" (e.g. "on-request", "on-failure", "untrusted" — any value where resolvePaperclipRunnerPermissionMode(provider, configured) !== configured).

Common situations: Agent config copied from a non-runner Codex integration that used interactive permission modes; user picked a permissive mode in the agent settings UI; schema/enum change added new Codex modes not yet qualified for runner use.

Related errors

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