paperclipai/paperclip · error · RouteError

managed_profile_unavailable

managed_profile_unavailable

Error message

The selected Claude Managed profile is not fully qualified on this Runner Lab server.

What it means

After the profile ID matches, resolveManagedProfile verifies the server is fully qualified to run Claude Managed: ANTHROPIC_API_KEY, a non-empty profile ID, ANTHROPIC_MANAGED_AGENT_ID, an ANTHROPIC_MANAGED_AGENT_VERSION that is a positive integer fitting in a signed 32-bit int, and ANTHROPIC_MANAGED_ENVIRONMENT_ID must all be present. If any is missing or invalid it throws 503 managed_profile_unavailable, signaling a server-side provisioning gap rather than a bad client request.

Source

Thrown at packages/paperclip-runner/scripts/capability-issue-thread-server.mjs:311

    ...(provider === "claude_managed" ? { managedProfileId, maxSessionListCostUsd } : {}),
    ...(provider === "aws_agentcore" ? { agentCoreProfileId, maxEstimatedSessionCostUsd } : {}),
    lifecyclePolicy,
  };
}

function resolveManagedProfile(configuration) {
  const profileId = process.env.PAPERCLIP_CLAUDE_MANAGED_PROFILE_ID?.trim() || configuration.managedProfileId;
  if (profileId !== configuration.managedProfileId) {
    throw new RouteError(400, "managed_profile_not_found", "The selected Claude Managed profile is not configured on this Runner Lab server.");
  }
  const anthropicAgentId = process.env.ANTHROPIC_MANAGED_AGENT_ID?.trim();
  const agentVersion = process.env.ANTHROPIC_MANAGED_AGENT_VERSION?.trim();
  const environmentId = process.env.ANTHROPIC_MANAGED_ENVIRONMENT_ID?.trim();
  const canonicalAgentVersion = agentVersion !== undefined
    && /^[1-9][0-9]*$/.test(agentVersion)
    && BigInt(agentVersion) <= 2_147_483_647n;
  if (!process.env.ANTHROPIC_API_KEY || !profileId || !anthropicAgentId || !canonicalAgentVersion || !environmentId) {
    throw new RouteError(
      503,
      "managed_profile_unavailable",
      "The selected Claude Managed profile is not fully qualified on this Runner Lab server.",
    );
  }
  return {
    profileId,
    anthropicAgentId,
    agentVersion,
    environmentId,
    betaVersion: "managed-agents-2026-04-01",
    maxSessionListCostUsd: configuration.maxSessionListCostUsd,
  };
}

function resolveAgentCoreProfile(configuration) {
  const required = (name) => {
    const value = process.env[name]?.trim();

View on GitHub (pinned to 5716fe907e)

Solutions

Set ANTHROPIC_API_KEY in the server environment and restart the Runner Lab server.
Set ANTHROPIC_MANAGED_AGENT_ID, ANTHROPIC_MANAGED_AGENT_VERSION (a positive integer ≤ 2147483647), and ANTHROPIC_MANAGED_ENVIRONMENT_ID to the values produced by the managed-profile provisioning step.
Re-run the server's managed profile provisioning/lab setup script to regenerate all required env vars.
Verify the env file actually loads (e.g. all vars exported) and the version string contains only digits with no leading zeros.

Example fix

// before
ANTHROPIC_API_KEY=sk-...
# ANTHROPIC_MANAGED_AGENT_VERSION unset
// after
ANTHROPIC_API_KEY=sk-...
ANTHROPIC_MANAGED_AGENT_ID=agent-42
ANTHROPIC_MANAGED_AGENT_VERSION=3
ANTHROPIC_MANAGED_ENVIRONMENT_ID=env-7

Defensive patterns

Strategy: validation

Validate before calling

function claudeManagedReady(env = process.env) {
  const v = env.ANTHROPIC_MANAGED_AGENT_VERSION?.trim() ?? "";
  return Boolean(
    env.ANTHROPIC_API_KEY?.trim() &&
    env.PAPERCLIP_CLAUDE_MANAGED_PROFILE_ID?.trim() &&
    env.ANTHROPIC_MANAGED_AGENT_ID?.trim() &&
    (/^[1-9][0-9]*$/.test(v) && BigInt(v) <= 2147483647n) &&
    env.ANTHROPIC_MANAGED_ENVIRONMENT_ID?.trim()
  );
}
if (!claudeManagedReady()) await runManagedProfileProvisioning();

Type guard

function isValidAgentVersion(v) {
  return typeof v === "string" && /^[1-9][0-9]*$/.test(v.trim()) && BigInt(v.trim()) <= 2147483647n;
}

Try / catch

try {
  await configureHarness(cfg);
} catch (e) {
  if (e.code === "managed_profile_unavailable") {
    // 503: server-side gap; surface to operator, do not blind-retry
    reportServerMisconfiguration(e.message);
  } else throw e;
}

Prevention

Add a server health/readiness check that asserts all ANTHROPIC_MANAGED_* vars before accepting requests.
Export the full env block produced by provisioning as a unit; never rotate one var alone.
Validate the agent version fits a 32-bit positive integer when bumping it.
Use a process manager env_file so partially sourced shells cannot drop vars.

When it happens

Trigger: Any of: ANTHROPIC_API_KEY unset; PAPERCLIP_CLAUDE_MANAGED_PROFILE_ID/configured profile empty; ANTHROPIC_MANAGED_AGENT_ID missing; ANTHROPIC_MANAGED_AGENT_VERSION absent, non-numeric, zero-prefixed, 0, negative, or > 2147483647; ANTHROPIC_MANAGED_ENVIRONMENT_ID missing.

Common situations: Fresh Runner Lab server provisioned without running the managed-profile setup; credentials rotated and API key removed from the environment; agent version bumped to a value exceeding the 32-bit guard; env file partially sourced so only some ANTHROPIC_MANAGED_* vars load.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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