--model must be the qualified Managed Agents model ${CLAUDE_

Error message

--model must be the qualified Managed Agents model ${CLAUDE_MANAGED_QUALIFIED_MODEL}

What it means

The Managed Agents beta only accepts the single qualified model id `claude-sonnet-5` exported as CLAUDE_MANAGED_QUALIFIED_MODEL. `validateManagedAgentSetup` throws this when the `--model` value is present but is not exactly that string. Aliases, snapshots, or newer model names are rejected client-side before any API call.

Source

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

  options: ManagedAgentSetupOptions,
  env: NodeJS.ProcessEnv = process.env,
): ValidatedSetup {
  const anthropicApiKey = env.ANTHROPIC_API_KEY?.trim();
  if (!anthropicApiKey) {
    throw new Error("ANTHROPIC_API_KEY is required in the CLI process environment");
  }
  if (!options.acknowledgeRetention) {
    throw new Error(
      "Pass --acknowledge-retention to enable the stateful beta Managed Agents service",
    );
  }

  const profileKey = required(options.profileKey, "--profile-key");
  const displayName = required(options.displayName, "--display-name");
  const apiKeySecretId = required(options.apiKeySecretId, "--api-key-secret-id");
  const model = required(options.model, "--model");
  if (model !== CLAUDE_MANAGED_QUALIFIED_MODEL) {
    throw new Error(
      `--model must be the qualified Managed Agents model ${CLAUDE_MANAGED_QUALIFIED_MODEL}`,
    );
  }
  if (!UUID_RE.test(apiKeySecretId)) {
    throw new Error("--api-key-secret-id must be a UUID");
  }

  const defaultMaxListCostUsd = Number(options.maxSessionListCostUsd);
  const cents = Math.round(defaultMaxListCostUsd * 100);
  if (
    !Number.isFinite(defaultMaxListCostUsd)
    || defaultMaxListCostUsd <= 0
    || !Number.isSafeInteger(cents)
    || cents <= 0
  ) {
    throw new Error("--max-session-list-cost-usd must resolve to at least one cent");
  }

View on GitHub (pinned to 5716fe907e)

Solutions

Use exactly --model claude-sonnet-5
Import/reference CLAUDE_MANAGED_QUALIFIED_MODEL when building the command programmatically instead of hardcoding
Check the CLI version's exported constant if unsure which model is current
Remove dated model suffixes or aliases from templates and scripts

Example fix

// before
const args = [...base, "--model", "claude-sonnet-5-20260101"];
// after
import { CLAUDE_MANAGED_QUALIFIED_MODEL } from "./managed-agent.js";
const args = [...base, "--model", CLAUDE_MANAGED_QUALIFIED_MODEL];

Defensive patterns

Strategy: validation

Validate before calling

import { CLAUDE_MANAGED_QUALIFIED_MODEL } from "./managed-agent.js";
if (model !== CLAUDE_MANAGED_QUALIFIED_MODEL) {
  throw new Error(`Managed Agents require --model ${CLAUDE_MANAGED_QUALIFIED_MODEL}, got ${model}`);
}

Type guard

function isQualifiedManagedModel(m: string): m is typeof CLAUDE_MANAGED_QUALIFIED_MODEL {
  return m === CLAUDE_MANAGED_QUALIFIED_MODEL;
}

Try / catch

try {
  await setupManagedAgent(opts);
} catch (err) {
  if (err instanceof Error && err.message.startsWith("--model must be")) {
    console.error(`Use --model ${CLAUDE_MANAGED_QUALIFIED_MODEL}`); process.exitCode = 2;
  } else throw err;
}

Prevention

Reference the exported CLAUDE_MANAGED_QUALIFIED_MODEL constant instead of hardcoding strings
Never reuse --model values from other Anthropic commands in managed-agent invocations
Strip dated suffixes/aliases from model config templates
Pin the CLI version so the expected qualified model is known

When it happens

Trigger: Passing `--model claude-sonnet-5-20260101`, `--model claude-sonnet-4-5`, `--model sonnet`, or any dated/alias variant; copying a --model value from a non-managed-agent command; hardcoding a model string in a script that predates the qualified-model requirement.

Common situations: Reusing flags from other Anthropic-based commands where dated model ids are the norm; upgrading the CLI and the pinned qualified model changed; fat-fingering the model name.

Related errors

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