{"record":{"id":"311c38fc58cb07a7","repo":"paperclipai/paperclip","slug":"agent-not-found-agentref","errorCode":null,"errorMessage":"Agent not found: ${agentRef}","messagePattern":"Agent not found: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/commands/client/agent.ts","lineNumber":744,"sourceCode":"  addCommonClientOptions(\n    agent\n      .command(\"wake\")\n      .description(\"Request a heartbeat wakeup for an agent\")\n      .argument(\"<agentRef>\", \"Agent ID or shortname/url-key\")\n      .option(\"-C, --company-id <id>\", \"Company ID for shortname/url-key lookup\")\n      .option(\"--source <source>\", \"Invocation source (timer, assignment, on_demand, automation)\", \"on_demand\")\n      .option(\"--trigger <trigger>\", \"Trigger detail (manual, ping, callback, system)\", \"manual\")\n      .option(\"--reason <text>\", \"Wakeup reason\")\n      .option(\"--payload <json>\", \"JSON object payload\")\n      .option(\"--idempotency-key <key>\", \"Wakeup idempotency key\")\n      .option(\"--force-fresh-session\", \"Request a fresh adapter session\")\n      .action(async (agentRef: string, opts: AgentWakeOptions) => {\n        try {\n          const ctx = resolveCommandContext(opts);\n          const query = opts.companyId ? `?${new URLSearchParams({ companyId: opts.companyId }).toString()}` : \"\";\n          const agentRow = await ctx.api.get<Agent>(`${apiPath`/api/agents/${agentRef}`}${query}`);\n          if (!agentRow) {\n            throw new Error(`Agent not found: ${agentRef}`);\n          }\n          const payload = wakeAgentSchema.parse({\n            source: opts.source,\n            triggerDetail: opts.trigger,\n            reason: opts.reason,\n            payload: parseJsonObject(opts.payload),\n            idempotencyKey: opts.idempotencyKey,\n            forceFreshSession: Boolean(opts.forceFreshSession),\n          });\n          const result = await ctx.api.post<AgentWakeupResponse>(apiPath`/api/agents/${agentRow.id}/wakeup`, payload);\n          printOutput(result, { json: ctx.json });\n        } catch (err) {\n          handleCommandError(err);\n        }\n      }),\n    { includeCompany: false },\n  );\n","sourceCodeStart":726,"sourceCodeEnd":762,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/client/agent.ts#L726-L762","documentation":"Thrown by the `paperclipai agent wake` action when the GET /api/agents/{agentRef} (with optional ?companyId=) returned a falsy value. The CLI resolves the agent by ref (id or slug) before issuing POST /api/agents/{id}/wakeup, and aborts if the lookup yielded nothing. Note the agent lookup is company-scoped when --company-id is supplied.","triggerScenarios":"agentRef does not match any agent id/slug. The agent exists but belongs to a different company than the resolved --company-id (or the default company in context). The API returned 404-shaped null (the client coerces not-found to undefined/null). Wrong apiBase pointing at an environment where the agent does not exist.","commonSituations":"Typo in the agent id/slug. Copy-pasting an agent ref from one Paperclip instance into a CLI pointed at another. Forgetting to set --company-id / PAPERCLIP_COMPANY_ID when the agent lives in a non-default company. Agent was deleted before the wake call.","solutions":["List agents to confirm the ref: `paperclipai agent list --company-id <co>`.","Pass the correct company: `paperclipai agent wake <ref> --company-id <co>`.","Confirm you are pointed at the right instance: check --api-base / context profile.","Use the agent's canonical id (starts with agt_) rather than a slug if slugs collide."],"exampleFix":"// before\npaperclipai agent wake my-agent\n// after\npaperclipai agent wake agt_abc123 --company-id cmp_xyz","handlingStrategy":"validation","validationCode":"import { PaperclipApiClient } from '../../client/http.js';\nasync function ensureAgent(api: PaperclipApiClient, ref: string, companyId?: string) {\n  const q = companyId ? `?${new URLSearchParams({ companyId }).toString()}` : '';\n  const row = await api.get(`/api/agents/${encodeURIComponent(ref)}${q}`).catch(() => null);\n  if (!row) throw new Error(`No agent matching '${ref}'${companyId ? ` in company ${companyId}` : ''}`);\n  return row;\n}","typeGuard":"function isAgentRow(v: unknown): v is { id: string } {\n  return typeof v === 'object' && v !== null && typeof (v as any).id === 'string';\n}","tryCatchPattern":"try { await wake(agentRef, opts); }\ncatch (err) {\n  const msg = err instanceof Error ? err.message : '';\n  if (msg.startsWith('Agent not found:')) {\n    console.error(`Unknown agent '${agentRef}'. Run: paperclipai agent list --company-id ${opts.companyId ?? ''}`);\n    process.exit(2);\n  }\n  throw err;\n}","preventionTips":["Resolve agents by canonical id (agt_...) rather than slug to avoid collisions.","Always pass --company-id when operating on a non-default company.","List before acting: `paperclipai agent list` to confirm refs.","Pin the apiBase/profile to the correct instance."],"tags":["cli","agent","not-found","company-scope"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}