paperclipai/paperclip · error

Pass --acknowledge-retention to enable the stateful beta Man

Error message

Pass --acknowledge-retention to enable the stateful beta Managed Agents service

What it means

The Managed Agents service is a stateful beta that retains Anthropic-side resources (environments, agents), so the CLI requires an explicit opt-in acknowledgement flag. `validateManagedAgentSetup` throws this when `options.acknowledgeRetention` is falsy. It is a deliberate friction gate, not a malfunction.

Source

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

    : {};
}

function required(value: string | undefined, label: string): string {
  const normalized = value?.trim() ?? "";
  if (!normalized) throw new Error(`${label} is required`);
  return normalized;
}

export function validateManagedAgentSetup(
  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);

View on GitHub (pinned to 5716fe907e)

Solutions

1. Add `--acknowledge-retention` to the command line
2. When invoking validateManagedAgentSetup in code, set acknowledgeRetention: true in the options object
3. Update wrapper scripts/templates that construct the argument list
4. Review the retention implications first — the flag exists because Anthropic retains beta resources

Example fix

// before
paperclip managed-agent setup --profile-key acme --display-name "Acme" --api-key-secret-id <uuid> --model claude-sonnet-5
// after
paperclip managed-agent setup --profile-key acme --display-name "Acme" --api-key-secret-id <uuid> --model claude-sonnet-5 --acknowledge-retention

const args = ["managed-agent", "setup", ...];
if (!opts.acknowledgeRetention) args.push("--acknowledge-retention");
// or in code:
if (!options.acknowledgeRetention) throw new Error("Refusing to run: retention not acknowledged");

function acknowledgesRetention(o: { acknowledgeRetention?: boolean }): o is typeof o & { acknowledgeRetention: true } {
  return o.acknowledgeRetention === true;
}

try {
  await setupManagedAgent(opts);
} catch (err) {
  if (err instanceof Error && err.message.includes("--acknowledge-retention")) {
    console.error("Add --acknowledge-retention after reviewing retention implications"); process.exitCode = 2;
  } else throw err;
}

When it happens

Trigger: Running the managed-agent setup command without `--acknowledge-retention`; passing the flag with no value in a way that resolves to false; calling `validateManagedAgentSetup` programmatically with `acknowledgeRetention` omitted from the options object.

Common situations: Copy-pasting an older command example from before the flag existed; wrapping the CLI in a script that builds args dynamically and drops the flag; assuming a `--yes`/`-y` style flag covers it.

Related errors

• ${label} is required
• Managed installs require Node.js ${MINIMUM_NODE_VERSION} or
• Import cancelled.
• Could not open your browser automatically. Open this URL man
• Unknown config key ${warning.path}; did you mean ${warning.s

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