{"record":{"id":"b580924c92796732","repo":"paperclipai/paperclip","slug":"api-key-secret-id-must-be-a-uuid","errorCode":null,"errorMessage":"--api-key-secret-id must be a UUID","messagePattern":"--api-key-secret-id must be a UUID","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/src/commands/managed-agent.ts","lineNumber":88,"sourceCode":"    throw new Error(\"ANTHROPIC_API_KEY is required in the CLI process environment\");\n  }\n  if (!options.acknowledgeRetention) {\n    throw new Error(\n      \"Pass --acknowledge-retention to enable the stateful beta Managed Agents service\",\n    );\n  }\n\n  const profileKey = required(options.profileKey, \"--profile-key\");\n  const displayName = required(options.displayName, \"--display-name\");\n  const apiKeySecretId = required(options.apiKeySecretId, \"--api-key-secret-id\");\n  const model = required(options.model, \"--model\");\n  if (model !== CLAUDE_MANAGED_QUALIFIED_MODEL) {\n    throw new Error(\n      `--model must be the qualified Managed Agents model ${CLAUDE_MANAGED_QUALIFIED_MODEL}`,\n    );\n  }\n  if (!UUID_RE.test(apiKeySecretId)) {\n    throw new Error(\"--api-key-secret-id must be a UUID\");\n  }\n\n  const defaultMaxListCostUsd = Number(options.maxSessionListCostUsd);\n  const cents = Math.round(defaultMaxListCostUsd * 100);\n  if (\n    !Number.isFinite(defaultMaxListCostUsd)\n    || defaultMaxListCostUsd <= 0\n    || !Number.isSafeInteger(cents)\n    || cents <= 0\n  ) {\n    throw new Error(\"--max-session-list-cost-usd must resolve to at least one cent\");\n  }\n\n  return {\n    anthropicApiKey,\n    profileKey,\n    displayName,\n    apiKeySecretId,","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/paperclipai/paperclip/blob/5716fe907e596ce73501408fc6efdb19fb61edf2/cli/src/commands/managed-agent.ts#L70-L106","documentation":"`--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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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)","Strip braces/quotes and re-paste the id","If your ids are UUIDv7 or non-RFC variant, this validator rejects them — use the secret's stored canonical id from the Paperclip API","Double-check you are not passing the agent or profile id by mistake"],"exampleFix":"// before\n--api-key-secret-id my-agent-key\n// after\n--api-key-secret-id 3f2c9a1e-7b4d-4e2a-9c1f-8d6b5a0e3c21","handlingStrategy":"validation","validationCode":"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;\nif (!UUID_RE.test(apiKeySecretId)) {\n  throw new Error(`apiKeySecretId must be a UUID (got \"${apiKeySecretId}\")`);\n}","typeGuard":"function isUuid(v: string): boolean {\n  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);\n}","tryCatchPattern":"try {\n  await setupManagedAgent(opts);\n} catch (err) {\n  if (err instanceof Error && err.message.includes(\"must be a UUID\")) {\n    console.error(\"Resolve the secret's UUID from the Paperclip API and retry\"); process.exitCode = 2;\n  } else throw err;\n}","preventionTips":["Copy secret UUIDs from the Paperclip API/UI, not from human-readable names","Strip braces, quotes, and whitespace before pasting ids","Store ids in config as plain canonical UUID strings","Remember the validator accepts only versions 1-5 with 89ab variant; v7-style ids will be rejected"],"tags":["cli","validation","uuid","input-format"],"backgroundTag":"invalid-uuid-format","analyzedSha":"5716fe907e596ce73501408fc6efdb19fb61edf2","analyzedAt":"2026-09-02T18:44:00.616Z","contentChangedAt":"2026-09-02T18:44:00.616Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}