paperclipai/paperclip · error

--api-key-secret-id must be a UUID

Error message

--api-key-secret-id must be a UUID

What it means

`--api-key-secret-id` must be the UUID of an existing Paperclip API-key secret, validated against a strict RFC-4122-style regex (lowercase/uppercase hex, version 1-5, variant 89ab). `validateManagedAgentSetup` throws this when the value passes the non-empty check but does not match that UUID shape. The check is purely syntactic; it does not confirm the secret exists.

Source

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

    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");
  }

  return {
    anthropicApiKey,
    profileKey,
    displayName,
    apiKeySecretId,

View on GitHub (pinned to 5716fe907e)

Solutions

1. Look up the API-key secret in Paperclip and copy its UUID exactly (8-4-4-4-12 hex, version 1-5, variant 8/9/a/b)
2. Strip braces/quotes and re-paste the id
3. If your ids are UUIDv7 or non-RFC variant, this validator rejects them — use the secret's stored canonical id from the Paperclip API
4. Double-check you are not passing the agent or profile id by mistake

Example fix

// before
--api-key-secret-id my-agent-key
// after
--api-key-secret-id 3f2c9a1e-7b4d-4e2a-9c1f-8d6b5a0e3c21

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
if (!UUID_RE.test(apiKeySecretId)) {
  throw new Error(`apiKeySecretId must be a UUID (got "${apiKeySecretId}")`);
}

function isUuid(v: string): boolean {
  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(v);
}

try {
  await setupManagedAgent(opts);
} catch (err) {
  if (err instanceof Error && err.message.includes("must be a UUID")) {
    console.error("Resolve the secret's UUID from the Paperclip API and retry"); process.exitCode = 2;
  } else throw err;
}

When it happens

Trigger: Passing a secret name/slug instead of its UUID; passing a Paperclip internal numeric id; truncating or copy-pasting a UUID with surrounding quotes, braces, or whitespace-adjacent characters; passing a v7 or non-standard UUID that fails the [89ab] variant check.

Common situations: Reading the id from a config file that stores the secret's human label; copying from a URL where the id was URL-encoded; older Paperclip instances storing non-RFC variant UUIDs; accidentally swapping in the agent id for the secret id.

Related errors

• --model must be the qualified Managed Agents model ${CLAUDE_
• --max-session-list-cost-usd must resolve to at least one cen
• unknown argument: ${args[index] ?? ""}
• OpenCode test drives require --model openrouter/<model>, wit
• --api-key-env must name a valid environment variable.

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