paperclipai/paperclip · error · Error

ACPX model must not be empty

Error message

ACPX model must not be empty

What it means

resolveQualifiedAcpxProfile validates the requested model string for a qualified ACPX agent profile before resolving it. A model that is empty or whitespace-only cannot be matched against the profile's qualification model, so it throws immediately. This keeps unqualified/blank model IDs from reaching the ACPX runtime.

Source

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

    agentProfileVersion: 1,
    agentServerPackage: "@agentclientprotocol/codex-acp",
    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

  1. Set a concrete model identifier in the driver/session configuration before opening the ACPX session.
  2. For the 'claude' profile set any non-empty model; for other agents set exactly the profile's qualificationModel (see QUALIFIED_ACPX_PROFILES).
  3. Validate/trim the model at your config boundary before calling any ACPX profile resolution API.

Example fix

// before
const driver = createAcpxDriver({ model: process.env.ACPX_MODEL ?? "" });
// after
const model = process.env.ACPX_MODEL;
if (!model || !model.trim()) throw new Error("ACPX_MODEL must be set");
const driver = createAcpxDriver({ model });
Defensive patterns

Strategy: validation

Validate before calling

if (typeof model !== "string" || !model.trim()) {
  throw new Error("ACPX model must be a non-empty string before opening a session");
}

Type guard

const hasModel = (v: unknown): v is string => typeof v === "string" && v.trim().length > 0;

Try / catch

try {
  driver.open({ model });
} catch (e) {
  if (e.message === "ACPX model must not be empty") {
    throw new ConfigError("Set ACPX model in driver config or ACPX_MODEL env var");
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling resolveQualifiedAcpxProfile(agent, model) — directly or via qualifiedProfile()/profile()/parseOpenParams()/evalSessionProviderVersion()/runEvalSessionCli()/validateAcpxDriverConfig() — with requestedModel = "", " ", or a string of only whitespace.

Common situations: A driver config omits the model field; an env var like ACPX_MODEL is unset or set to empty string; UI/CLI passes through an untouched empty input; trimming logic upstream strips a placeholder value away entirely.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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