paperclipai/paperclip · error · RouteError

invalid_acpx_agent

invalid_acpx_agent

Error message

ACPX agent must be claude or codex.

What it means

Guard in harnessConfiguration: for the 'acpx' provider, source.acpxAgent must be one of the qualified agents (claude or codex) whose keys exist in ACPX_QUALIFIED_MODELS; anything else throws RouteError(400,'invalid_acpx_agent'). It fires when the client names an unsupported ACPX agent (e.g. 'pi' or an unqualified/typo'd value).

Source

Thrown at packages/paperclip-runner/scripts/capability-issue-thread-server.mjs:229

  if (provider !== "codex" && provider !== "opencode" && provider !== "claude_managed" && provider !== "aws_agentcore" && provider !== "acpx") {
    throw new RouteError(400, "invalid_provider", "Provider must be codex, opencode, claude_managed, aws_agentcore, or acpx.");
  }
  const rawModel = source.model === undefined ? fallbackModel : source.model;
  const model = rawModel === undefined || rawModel === null ? "" : String(rawModel).trim();
  if (model.length > 256) throw new RouteError(400, "invalid_model", "Model is too long.");
  if (provider === "opencode" && (!model || !model.includes("/"))) {
    throw new RouteError(400, "invalid_model", "OpenCode requires a provider/model value.");
  }
  if (provider === "claude_managed" && model !== "claude-sonnet-5") {
    throw new RouteError(400, "invalid_model", "Claude Managed requires exact model claude-sonnet-5.");
  }
  if (provider === "aws_agentcore" && model !== "global.anthropic.claude-sonnet-4-6") {
    throw new RouteError(400, "invalid_model", "AWS AgentCore requires exact model global.anthropic.claude-sonnet-4-6.");
  }
  const acpxAgent = source.acpxAgent === undefined ? "codex" : String(source.acpxAgent).trim();
  if (provider === "acpx") {
    if (!(acpxAgent in ACPX_QUALIFIED_MODELS)) {
      throw new RouteError(400, "invalid_acpx_agent", "ACPX agent must be claude or codex.");
    }
    if (model !== ACPX_QUALIFIED_MODELS[acpxAgent]) {
      throw new RouteError(400, "invalid_model", `The qualified ACPX ${acpxAgent} profile requires exact model ${ACPX_QUALIFIED_MODELS[acpxAgent]}.`);
    }
  }
  const requestedManagedProfileId = source.managedProfileId === undefined || source.managedProfileId === null
    ? "default"
    : String(source.managedProfileId).trim();
  const configuredManagedProfileId = process.env.PAPERCLIP_CLAUDE_MANAGED_PROFILE_ID?.trim();
  const managedProfileId = provider === "claude_managed" && requestedManagedProfileId === "default" && configuredManagedProfileId
    ? configuredManagedProfileId
    : requestedManagedProfileId;
  const maxSessionListCostUsd = source.maxSessionListCostUsd === undefined || source.maxSessionListCostUsd === null
    ? 1
    : Number(source.maxSessionListCostUsd);
  if (provider === "claude_managed" && !managedProfileId) {
    throw new RouteError(400, "invalid_managed_profile", "Claude Managed requires a qualified profile ID.");
  }

View on GitHub (pinned to 5716fe907e)

Solutions

1. Set acpxAgent to exactly 'claude' or 'codex'.
2. Remove the acpxAgent override so the default qualified agent is used.
3. Check ACPX_QUALIFIED_MODELS in the script for the currently supported agent set before sending a custom value.

When it happens

Trigger: Thrown at packages/paperclip-runner/scripts/capability-issue-thread-server.mjs:229 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@5716fe907e (2026-09-02). Data as JSON: /api/errors/874ac9ef2ed10fa0. Report an issue: GitHub.