paperclipai/paperclip · error · Error

ACPX ${agent} profile requires exact model ${profile.qualifi

Error message

ACPX ${agent} profile requires exact model ${profile.qualificationModel}; received ${requestedModel}

What it means

Qualified ACPX agent profiles other than 'claude' are pinned: the requested model must exactly equal the profile's qualificationModel. If it differs, resolveQualifiedAcpxProfile throws with the expected model and the received value. Only the claude profile accepts an arbitrary non-empty model.

Source

Thrown at packages/paperclip-runner/src/drivers/acpx/qualified-profiles.ts:91

    agentServerVersion: "1.6.2",
    agentRuntimePackage: "@openai/codex",
    agentRuntimeVersion: "0.153.4",
    commandDigest:
      "sha256:c4538599d1ab767db5dff50934f13bb5ba313a59d9c4a83e993fac4617ea63d3",
    qualificationModel: "gpt-5.6-sol",
    reportedModelId: "gpt-5.6-sol",
    permissionPolicy: "interactive",
  },
});

export function resolveQualifiedAcpxProfile(
  agent: QualifiedAcpxAgent,
  requestedModel: string,
): QualifiedAcpxProfile {
  const profile = QUALIFIED_ACPX_PROFILES[agent];
  if (!requestedModel.trim()) throw new Error("ACPX model must not be empty");
  if (agent !== "claude" && requestedModel !== profile.qualificationModel) {
    throw new Error(
      `ACPX ${agent} profile requires exact model ${profile.qualificationModel}; received ${requestedModel}`,
    );
  }
  return { ...structuredClone(profile), qualificationModel: requestedModel, reportedModelId: requestedModel };
}

function deepFreeze<T>(value: T): T {
  if (typeof value !== "object" || value === null || Object.isFrozen(value))
    return value;
  Object.freeze(value);
  for (const child of Object.values(value)) deepFreeze(child);
  return value;
}

View on GitHub (pinned to 01ad858492)

Solutions

Read the expected model from the error message and set requestedModel to exactly profile.qualificationModel for that agent.
Use the 'claude' profile if you need arbitrary model ids — it is the only profile with a free-form model.
Check QUALIFIED_ACPX_PROFILES in packages/paperclip-runner/src/drivers/acpx/qualified-profiles.ts for the current pinned ids after upgrading the runner package.
If a new model version should be qualified, update the profile's qualificationModel in code (or upgrade the package) rather than overriding the string at call sites.

Example fix

// before
resolveQualifiedAcpxProfile("codex", "gpt-5.1"); // wrong pin
// after
resolveQualifiedAcpxProfile("codex", "gpt-5.1-codex"); // matches qualificationModel

Defensive patterns

Strategy: validation

Validate before calling

import { QUALIFIED_ACPX_PROFILES } from "@paperclip/paperclip-runner/drivers/acpx/qualified-profiles";
if (agent !== "claude" && model !== QUALIFIED_ACPX_PROFILES[agent].qualificationModel) {
  throw new Error(`${agent} requires model ${QUALIFIED_ACPX_PROFILES[agent].qualificationModel}`);
}

Try / catch

try {
  resolveQualifiedAcpxProfile(agent, model);
} catch (e) {
  if (e.message.includes("requires exact model")) {
    // surface the expected model from the message to the user/config
  }
  throw e;
}

Prevention

Source model ids from the profile definitions, not from free-form config, for non-claude agents.
Re-check pinned model ids after every runner package upgrade.
Avoid copy-pasting model ids across providers/agents.

When it happens

Trigger: Calling resolveQualifiedAcpxProfile(agent, requestedModel) (or any caller: qualifiedProfile, profile, parseOpenParams, evalSessionProviderVersion, runEvalSessionCli, validateAcpxDriverConfig) where agent is a non-claude qualified agent and requestedModel !== QUALIFIED_ACPX_PROFILES[agent].qualificationModel.

Common situations: Typo or alias in the model id (e.g. missing a date suffix); newer/older model versions from a changelog not matching the qualified pin; copy-pasting a model id from another provider; a config template using a different default model.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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