{"record":{"id":"9afb63a327def237","repo":"paperclipai/paperclip","slug":"agent-not-found-agentref-9afb63","errorCode":null,"errorMessage":"Agent not found: ${agentRef}","messagePattern":"Agent not found: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/commands/client/prompt.ts","lineNumber":152,"sourceCode":"    title: opts.title,\n    wake: opts.wake !== false,\n  });\n  return result;\n}\n\nexport async function runBoardPrompt(\n  agentRef: string,\n  prompt: string,\n  opts: PromptOptions,\n): Promise<PromptResult> {\n  const ctx = resolveCommandContext(opts, { requireCompany: true });\n  if (ctx.profile.persona && ctx.profile.persona !== \"board\") {\n    throw new Error(`Profile '${ctx.profileName}' is persona=${ctx.profile.persona}; use an agent prompt command or a board profile.`);\n  }\n  const body = normalizePrompt(prompt);\n  const query = new URLSearchParams({ companyId: ctx.companyId ?? \"\" });\n  const agent = await ctx.api.get<Agent>(`${apiPath`/api/agents/${agentRef}`}?${query.toString()}`);\n  if (!agent) throw new Error(`Agent not found: ${agentRef}`);\n\n  return createOrCommentForAgent({\n    api: ctx.api,\n    actor: \"board\",\n    agent,\n    companyId: ctx.companyId ?? agent.companyId,\n    prompt: body,\n    issueId: opts.issue,\n    title: opts.title,\n    wake: opts.wake !== false,\n  });\n}\n\nasync function createOrCommentForAgent(input: {\n  api: {\n    apiBase: string;\n    post<T>(path: string, body?: unknown): Promise<T | null>;\n  };","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/client/prompt.ts#L134-L170","documentation":"`runBoardPrompt` looks up the target agent via `GET /api/agents/<agentRef>?companyId=<id>`. If the API returns a falsy body (no matching agent), the function throws with the unresolved reference. The lookup is scoped by `companyId` from the resolved context, so an agent that exists in another company will not be found.","triggerScenarios":"Passing an `--agent` value (ID, shortname, or url-key) that does not exist; passing a valid agent ref but with the wrong `--company-id` / profile companyId; the agent was deleted or the shortname/url-key changed.","commonSituations":"Typo in the agent shortname; copying an agent ID from one company into a command run against another; stale url-key after an agent was renamed; forgetting `-C` when the profile has no default company.","solutions":["List agents in the target company to copy the exact ref: `paperclipai agent list -C <companyId>`","Confirm the `--company-id` (or profile companyId / `PAPERCLIP_COMPANY_ID`) matches the company that owns the agent","Try the agent's stable ID instead of the shortname/url-key, which can be renamed"],"exampleFix":"# before\npaperclipai board prompt --agent wrong-name \"do work\" -C comp-1\n# after\npaperclipai board prompt --agent agent_01H... \"do work\" -C comp-1","handlingStrategy":"validation","validationCode":"// Preflight: confirm the agent exists in the company before prompting\nasync function agentExists(api: { get<T>(p: string): Promise<T | null> }, ref: string, companyId: string): Promise<boolean> {\n  const q = new URLSearchParams({ companyId });\n  return Boolean(await api.get(`/api/agents/${encodeURIComponent(ref)}?${q}`));\n}\nif (!(await agentExists(ctx.api, agentRef, ctx.companyId ?? \"\"))) {\n  throw new Error(`No agent '${agentRef}' in company '${ctx.companyId}'`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  const agent = await ctx.api.get(`/api/agents/${agentRef}?${query}`);\n  if (!agent) throw new Error(`Agent not found: ${agentRef}`);\n} catch (err) {\n  console.error(`Agent lookup failed: ${err instanceof Error ? err.message : err}`);\n  process.exit(1);\n}","preventionTips":["List agents first with `agent list -C <companyId>` to copy the exact ref","Prefer stable agent IDs over shortnames/url-keys that can be renamed","Always pass `-C <companyId>` when the profile has no default company"],"tags":["cli","agent","lookup","company-scope","validation"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}