{"record":{"id":"6e96f3281e408ff8","repo":"paperclipai/paperclip","slug":"agent-not-found-agentref-6e96f3","errorCode":null,"errorMessage":"Agent not found: ${agentRef}","messagePattern":"Agent not found: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/commands/client/token.ts","lineNumber":222,"sourceCode":"      .argument(\"<keyId>\", \"Board API key ID\")\n      .action(async (keyId: string, opts: BaseClientOptions) => {\n        try {\n          const ctx = resolveCommandContext(opts);\n          const result = await ctx.api.delete<{ ok: true; keyId: string }>(apiPath`/api/board-api-keys/${keyId}`);\n          printOutput(result ?? { ok: true, keyId }, { json: ctx.json });\n        } catch (err) {\n          handleCommandError(err);\n        }\n      }),\n  );\n}\n\nasync function resolveAgent(api: { get<T>(path: string): Promise<T | null> }, companyId: string, agentRef: string): Promise<Agent> {\n  const trimmed = agentRef.trim();\n  if (!trimmed) throw new Error(\"Agent reference is required\");\n  if (/^[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(trimmed)) {\n    const agent = await api.get<Agent>(apiPath`/api/agents/${trimmed}`);\n    if (!agent || agent.companyId !== companyId) throw new Error(`Agent not found: ${agentRef}`);\n    return agent;\n  }\n  const query = new URLSearchParams({ companyId });\n  const agent = await api.get<Agent>(`${apiPath`/api/agents/${trimmed}`}?${query.toString()}`);\n  if (!agent || agent.companyId !== companyId) throw new Error(`Agent not found: ${agentRef}`);\n  return agent;\n}\n\nfunction resolveBoardKeyExpiresAt(opts: BoardTokenOptions): Date | null | undefined {\n  if (opts.neverExpires) return null;\n  if (opts.expiresAt?.trim()) {\n    const date = new Date(opts.expiresAt.trim());\n    if (!Number.isFinite(date.getTime())) throw new Error(`Invalid --expires-at value: ${opts.expiresAt}`);\n    return date;\n  }\n  if (opts.ttlDays?.trim()) {\n    const days = Number(opts.ttlDays);\n    if (!Number.isFinite(days) || days <= 0) throw new Error(`Invalid --ttl-days value: ${opts.ttlDays}`);","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/client/token.ts#L204-L240","documentation":"Thrown by resolveAgent (token.ts:222) on the UUID branch: the input matched the UUID regex, GET /api/agents/{uuid} either resolved null OR returned an agent whose companyId does not match the requested company. Enforces company-scoped agent lookup.","triggerScenarios":"Passing a syntactically valid UUID that does not exist, exists in a different company, or belongs to no company. The company boundary check (`agent.companyId !== companyId`) rejects cross-company agent references.","commonSituations":"Copy-pasting an agent UUID from another company, stale UUID after an agent was deleted/recreated, or a wrong --company-id that does not own the agent.","solutions":["Confirm the UUID belongs to the given --company-id via the board UI or GET /api/agents?companyId=...","Re-fetch the agent list for the correct company and copy the current UUID.","If the agent was deleted, recreate it or use its successor."],"exampleFix":"// before\n--company-id companyA --agent <uuid-from-companyB>\n// after\n--company-id companyB --agent <same-uuid>","handlingStrategy":"try-catch","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;\nasync function findAgentInCompany(api, companyId: string, uuid: string) {\n  if (!UUID_RE.test(uuid)) return null;\n  const agent = await api.get<Agent>(`/api/agents/${uuid}`);\n  return agent && agent.companyId === companyId ? agent : null;\n}","typeGuard":"function isUuidBelongingToCompany(agent: Agent | null, companyId: string): agent is Agent {\n  return !!agent && agent.companyId === companyId;\n}","tryCatchPattern":"try {\n  const agent = await resolveAgent(ctx.api, companyId, agentRef);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith(\"Agent not found\")) {\n    console.error(`Agent ${agentRef} is missing or not in company ${companyId}.`);\n  }\n  throw err;\n}","preventionTips":["Copy agent UUIDs from the same company you target with --company-id.","Re-fetch the agent list when a UUID stops resolving.","Use UUIDs rather than names to avoid cross-company ambiguity."],"tags":["cli","agent-resolution","company-scoping","uuid"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}