Existing Anthropic Agent model does not match the requested

Error message

Existing Anthropic Agent model does not match the requested pinned model ${expectedModel}

What it means

assertManagedAgentModel enforces that an existing Anthropic Agent runs exactly the pinned model requested by the caller (e.g. claude-sonnet-4-5). The agent's model field (string or object with .id) must strictly equal the expected model string; any mismatch aborts setup rather than silently re-pointing the versioned agent at a different model.

Source

Thrown at cli/src/commands/managed-agent.ts:314

  const agent = await anthropicRequest(key, "POST", "/v1/agents", {
    name: `Paperclip · ${options.displayName}`,
    description: "Versioned Paperclip remote agent; runnerd supplies session tools.",
    model: options.model,
    system: CLAUDE_MANAGED_SYSTEM_PROMPT,
    tools: [],
    mcp_servers: [],
    skills: [],
    metadata: { paperclip_profile: options.profileKey },
  });
  assertSafeManagedAgent(agent);
  assertManagedAgentModel(agent, options.model);
  return agent;
}

function assertManagedAgentModel(agent: Record<string, unknown>, expectedModel: string): void {
  const model = typeof agent.model === "string" ? agent.model : record(agent.model).id;
  if (model !== expectedModel) {
    throw new Error(
      `Existing Anthropic Agent model does not match the requested pinned model ${expectedModel}`,
    );
  }
}

export async function setupManagedAgent(options: ManagedAgentSetupOptions): Promise<void> {
  const validated = validateManagedAgentSetup(options);
  const normalizedOptions: ManagedAgentSetupOptions = {
    ...options,
    profileKey: validated.profileKey,
    displayName: validated.displayName,
    apiKeySecretId: validated.apiKeySecretId,
    model: validated.model,
    agentId: validated.agentId,
    agentVersion: validated.agentVersion,
    environmentId: validated.environmentId,
  };
  const [environment, agent] = await Promise.all([

View on GitHub (pinned to 5716fe907e)

Solutions

Align the requested pinned model with the existing agent's actual model (read it from the Anthropic console or GET /v1/agents/:id).
Delete or archive the old agent and let a non-probe setup create a new one with the new model.
Pass the correct --agent-id for an agent that already matches the requested model.
Check for model alias drift — pin a concrete model id instead of a moving alias.

Example fix

// before: config pins new model but remote agent is older
{ "model": "claude-sonnet-4-5" }   // remote agent: claude-sonnet-4-20250514
// after: either pin the actual remote model
{ "model": "claude-sonnet-4-20250514" }
// or recreate the agent with the new model (run without probe after removing the old one)

Defensive patterns

Strategy: validation

Validate before calling

// compare before invoking setup
const agent = await anthropicRequest(key, "GET", `/v1/agents/${agentId}`);
const model = typeof agent.model === "string" ? agent.model : agent.model?.id;
if (model !== expectedModel) {
  console.warn(`Agent ${agentId} runs ${model}, config pins ${expectedModel} — recreate or realign.`);
}

Type guard

function agentMatchesModel(agent: Record<string, unknown>, expected: string): boolean {
  const model = typeof agent.model === "string" ? agent.model
    : (typeof agent.model === "object" && agent.model !== null && typeof (agent.model as any).id === "string"
      ? (agent.model as any).id as string : undefined);
  return model === expected;
}

Try / catch

try {
  await setupManagedAgent(options);
} catch (e) {
  if (e instanceof Error && e.message.startsWith("Existing Anthropic Agent model does not match")) {
    // surface actionable guidance to the operator instead of a raw stack
    throw new Error(`${e.message}. Realign the pinned model or delete/recreate the managed agent.`, { cause: e });
  }
  throw e;
}

Prevention

Pin concrete model ids, not moving aliases.
When changing the pinned model, plan a delete-and-recreate of the managed agent.
Verify the agent's current model before re-running setup after config edits.
Keep one source of truth for the model string shared by config and setup.

When it happens

Trigger: resolveAgent or setupManagedAgent encounters an agent whose returned model differs from options.model — e.g. a caller upgrades the pinned model string in config while the remote agent was created with the older model, or an --agent-id is passed whose model differs from the requested one.

Common situations: Changing the pinned Claude model in Paperclip settings after the agent was created; Anthropic returning a model object whose id differs from the alias you passed (alias resolution/version skew); manually editing the agent's model in the Anthropic console.

Related errors

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