paperclipai/paperclip · error · Error

eval-session acpxAgent must be codex or claude

Error message

eval-session acpxAgent must be codex or claude

What it means

acpxAgent, when provided, must be exactly 'codex' or 'claude'. parseEvalSessionRequest fail-closed rejects any other string value because only these two ACPX agent profiles are qualified for eval sessions at the executable boundary. This is a strict allowlist, not a free-text field.

Source

Thrown at packages/paperclip-runner/src/cli/eval-session-contract.ts:246

      "eval-session provider is unsupported by CapabilityLiveSessionService",
    );
  }
  const provider = providerValue;
  const driver = expectedEvalSessionDriver(provider);
  if (input.driver !== undefined && input.driver !== driver) {
    throw new Error("eval-session provider/driver mismatch");
  }
  // The original Evalbook v1 producer serialized absent provider-specific
  // options as JSON null. Preserve compatibility with those immutable request
  // artifacts while continuing to reject non-null values for the wrong lane.
  const acpxAgent = input.acpxAgent === null ? undefined : input.acpxAgent;
  if (acpxAgent === "pi") throw new Error("The Pi ACPX profile is not available");
  if (
    acpxAgent !== undefined &&
    acpxAgent !== "codex" &&
    acpxAgent !== "claude"
  ) {
    throw new Error("eval-session acpxAgent must be codex or claude");
  }
  if (provider !== "acpx" && acpxAgent !== undefined) {
    throw new Error("eval-session acpxAgent requires provider acpx");
  }
  const managedProfileInput = input.managedProfile === null
    ? undefined
    : input.managedProfile;
  const agentCoreProfileInput = input.agentCoreProfile === null
    ? undefined
    : input.agentCoreProfile;
  const managedProfile = provider === "claude_managed"
    ? parseManagedProfile(managedProfileInput)
    : undefined;
  const agentCoreProfile = provider === "aws_agentcore"
    ? parseAgentCoreProfile(agentCoreProfileInput)
    : undefined;
  if (provider !== "claude_managed" && managedProfileInput !== undefined) {
    throw new Error("eval-session managedProfile requires provider claude_managed");

View on GitHub (pinned to 01ad858492)

Solutions

1. Set acpxAgent to exactly 'codex' or 'claude' (lowercase).
2. Omit acpxAgent entirely if no ACPX-specific agent is needed.
3. Fix the casing/typo in the config or generator script.
4. Validate the value against the allowlist before constructing the request.

Example fix

// before
const request = { schema, provider: "acpx", acpxAgent: "Codex", ... };
// after
const request = { schema, provider: "acpx", acpxAgent: "codex", ... };

function assertValidAcpxAgent(request: { acpxAgent?: unknown }): void {
  const a = request.acpxAgent;
  if (a !== undefined && a !== "codex" && a !== "claude") {
    throw new Error(`acpxAgent '${String(a)}' invalid; must be 'codex' or 'claude' (exact lowercase)`);
  }
}

function isAcpxAgent(v: unknown): v is "codex" | "claude" {
  return typeof v === "string" && (v === "codex" || v === "claude");
}

try {
  const parsed = parseEvalSessionRequest(raw);
} catch (err) {
  if (err instanceof Error && err.message === "eval-session acpxAgent must be codex or claude") {
    console.error(`acpxAgent '${raw.acpxAgent}' not allowed; use exactly 'codex' or 'claude'.`);
  } else throw err;
}

When it happens

Trigger: Calling parseEvalSessionRequest with input.acpxAgent set to any string other than 'codex', 'claude', or the separately rejected 'pi' — e.g. 'gpt', 'Codex' (wrong case), 'codex-cli', or an empty/typo value like 'cdoex'.

Common situations: Typo or wrong casing of the agent name; passing a CLI binary name instead of the profile name; config generated from a list of all ACPX agents rather than the supported subset; renaming across versions.

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

• invalid_provider
• ${path} must be an object
• ${path} must be a non-empty string
• ${path} must be a positive safe integer
• ${path} must be a positive finite number

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