paperclipai/paperclip · error · PaperclipRunnerProviderProfileError

paperclip_runner_claude_managed_beta_unqualified

paperclip_runner_claude_managed_beta_unqualified

Error message

The Claude Managed profile beta version is not qualified.

What it means

When a run selects the claude_managed backend, resolvePaperclipRunnerNativeProviderInput loads the stored Claude Managed agent profile and requires its betaVersion to equal CLAUDE_MANAGED_BETA_VERSION ('managed-agents-2026-04-01'). This beta version gates the Anthropic Managed Agents API contract ('anthropic-beta' header) Paperclip is qualified against. If the stored profile records any other beta version, the run is refused rather than executed against an unqualified API surface.

Source

Thrown at server/src/services/native-runtime/provider-profile.ts:497

      ) as "approve-all" | "approve-reads" | "deny-all",
    };
  }
  if (profile.provider === "claude_managed") {
    const stored = input.managedProfile;
    if (
      !stored
      || (
        profile.managedProfileId !== stored.id
        && profile.managedProfileId !== stored.profileKey
      )
    ) {
      throw new PaperclipRunnerProviderProfileError(
        "paperclip_runner_claude_managed_profile_mismatch",
        "The qualified Claude Managed profile does not match the adapter selection.",
      );
    }
    if (stored.betaVersion !== CLAUDE_MANAGED_BETA_VERSION) {
      throw new PaperclipRunnerProviderProfileError(
        "paperclip_runner_claude_managed_beta_unqualified",
        "The Claude Managed profile beta version is not qualified.",
      );
    }
    const model = profile.model ?? optionalString(stored.defaultModel);
    const maxSessionListCostUsd = profile.maxSessionListCostUsd
      ?? stored.defaultMaxListCostCents / 100;
    if (!model) {
      throw new PaperclipRunnerProviderProfileError(
        "paperclip_runner_claude_managed_model_invalid",
        "The Claude Managed profile requires a model.",
      );
    }
    if (model !== CLAUDE_MANAGED_QUALIFIED_MODEL) {
      throw new PaperclipRunnerProviderProfileError(
        "paperclip_runner_claude_managed_model_unqualified",
        `The Claude Managed profile requires exact model ${CLAUDE_MANAGED_QUALIFIED_MODEL}.`,
      );

View on GitHub (pinned to 01ad858492)

Solutions

  1. Re-register the managed agent profile with the current CLI so setupManagedAgent stores betaVersion='managed-agents-2026-04-01' (paperclip managed-agent setup / setupManagedAgent).
  2. Update the profile row's betaVersion to CLAUDE_MANAGED_BETA_VERSION via the managed-agent profile service or admin API, then retry the run.
  3. Upgrade the Paperclip server and packages to matching versions so the qualification check and profile storage agree on the beta version.
  4. If a downgrade is intentional, pin/restore the code version that matches the stored betaVersion instead of changing data.

Example fix

// before (stored profile)
{ "profileKey": "acme-managed", "betaVersion": "managed-agents-2026-01-15", ... }
// after
{ "profileKey": "acme-managed", "betaVersion": "managed-agents-2026-04-01", ... }
Defensive patterns

Strategy: validation

Validate before calling

import { CLAUDE_MANAGED_BETA_VERSION } from "@paperclipai/cli/managed-agent";
if (profile.provider === "claude_managed" && storedProfile.betaVersion !== CLAUDE_MANAGED_BETA_VERSION) {
  throw new Error(`Profile ${storedProfile.profileKey} needs re-registration: beta ${storedProfile.betaVersion} != ${CLAUDE_MANAGED_BETA_VERSION}`);
}

Type guard

const isQualifiedBeta = (p: { betaVersion?: string | null }): p is { betaVersion: typeof CLAUDE_MANAGED_BETA_VERSION } =>
  p.betaVersion === CLAUDE_MANAGED_BETA_VERSION;

Try / catch

try {
  await executeRun(run);
} catch (e) {
  if (e instanceof PaperclipRunnerProviderProfileError && e.code === "paperclip_runner_claude_managed_beta_unqualified") {
    await reRegisterManagedAgentProfile(profile.managedProfileId); // refresh betaVersion, then retry once
  } else throw e;
}

Prevention

When it happens

Trigger: A run executes with provider=claude_managed and a stored managedProfile whose betaVersion field differs from 'managed-agents-2026-04-01' — e.g. the profile was created by an older CLI (setupManagedAgent) or server version before the current beta string, or the profile row's betaVersion was hand-edited.

Common situations: Upgrading Paperclip (server or @paperclipai CLI) where managed agent profiles created under a previous beta version persist in the database; restoring an old database snapshot with stale profiles; Anthropic changing the managed-agents beta date while local profile records lag behind.

Related errors

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