paperclipai/paperclip · error · Error

Select Codex to use the native Codex runner.

Error message

Select Codex to use the native Codex runner.

What it means

Thrown by `testEnvironment` in the adapter registry when an ACPX profile is being validated but `profile.acpxAgent` is not `"claude"`. Despite the wording, the check enforces that only the Claude ACPX agent can use the native Codex runner path; any other acpxAgent value fails environment testing with this message.

Source

Thrown at server/src/adapters/registry.ts:408

        ? error
        : new PaperclipRunnerProviderProfileError(
            "paperclip_runner_provider_unsupported",
            "Paperclip Runner provider configuration is invalid.",
          );
      return {
        adapterType: "paperclip_runner",
        status: "fail" as const,
        testedAt: new Date().toISOString(),
        checks: [{
          code: profileError.code,
          level: "error" as const,
          message: profileError.message,
        }],
      };
    }
    if (profile.provider === "acpx") {
      try {
        if (profile.acpxAgent !== "claude") throw new Error("Select Codex to use the native Codex runner.");
        const target = context.executionTarget;
        if (target?.kind === "remote") {
          const probe = await runAdapterExecutionTargetShellCommand(
            `acpx-platform-${crypto.randomUUID()}`, target, "uname -s && uname -m",
            { cwd: target.remoteCwd, env: {}, timeoutSec: 15 },
          );
          if (probe.timedOut || probe.exitCode !== 0) throw new Error("Could not verify the remote ACPX runner platform.");
          const [os, arch] = probe.stdout.trim().split(/\s+/);
          if (!((os === "Linux" && arch === "x86_64") || (os === "Darwin" && ["arm64", "x86_64"].includes(arch ?? "")))) {
            throw new Error("ACPX Claude requires Linux x64 or macOS ARM64/x64.");
          }
          return {
            adapterType: "paperclip_runner", status: "warn" as const, testedAt: new Date().toISOString(),
            checks: [{ code: "acpx_remote_runtime_unverified", level: "warn" as const,
              message: "The remote platform is supported. Runtime package integrity and readiness must still be verified by the remote runner before launch." }],
          };
        }
        const { probeAcpxClaudeInstallation } = await import("@paperclipai/paperclip-runner/live");

View on GitHub (pinned to 01ad858492)

Solutions

1. Set `profile.acpxAgent` to `"claude"` in the adapter profile and re-run the environment test.
2. If you intended a non-Claude agent, use the appropriate provider instead of `acpx`.
3. Fix typos or casing in the acpxAgent value (must be exactly `"claude"`).
4. Re-create the profile through the UI so validation constrains acpxAgent to the supported value.

Example fix

// before
const profile = { provider: "acpx", acpxAgent: "codex" };
// after
const profile = { provider: "acpx", acpxAgent: "claude" };

if (profile.provider === "acpx" && profile.acpxAgent !== "claude") {
  throw new Error("ACPX profiles must set acpxAgent to 'claude'");
}

function isSupportedAcpxProfile(profile) {
  return profile.provider !== "acpx" || profile.acpxAgent === "claude";
}

try {
  await registry.testEnvironment(profile, context);
} catch (err) {
  if (err.message.includes("Select Codex to use the native Codex runner")) {
    profile.acpxAgent = "claude";
    await registry.testEnvironment(profile, context);
  } else throw err;
}

When it happens

Trigger: Calling the adapter environment-test path with a profile where `provider === "acpx"` and `profile.acpxAgent` set to something other than `"claude"` (e.g. a codex/other agent value or a stale/typo'd agent name).

Common situations: User selected the wrong agent in the ACPX profile UI; profile JSON edited by hand with an unsupported acpxAgent value; older profile created before the acpxAgent field was constrained; migration left an unexpected default.

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

• ${prefix}: the capability must be an object.
• ${prefix}: "panelMode" must be one of ${ADAPTER_LOGIN_PANEL_
• ${prefix}: "sandboxTransport" must be one of ${ADAPTER_LOGIN
• ${prefix}: "timeoutPolicy" must be one of ${ADAPTER_LOGIN_TI
• ${prefix}: "getCommand" must be a function.

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