{"record":{"id":"1bc115930b133076","repo":"paperclipai/paperclip","slug":"agent-reference-is-required","errorCode":null,"errorMessage":"Agent reference is required","messagePattern":"Agent reference is required","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/commands/client/prompt.ts","lineNumber":250,"sourceCode":"    reason,\n    payload: { issueId },\n  });\n}\n\nfunction normalizePrompt(prompt: string): string {\n  const normalized = prompt.trim();\n  if (!normalized) throw new Error(\"Prompt text is required\");\n  return normalized;\n}\n\nfunction defaultPromptTitle(prompt: string): string {\n  const firstLine = prompt.split(/\\r?\\n/).map((line) => line.trim()).find(Boolean) ?? \"Prompt handoff\";\n  return firstLine.length > 100 ? `${firstLine.slice(0, 97)}...` : firstLine;\n}\n\nfunction assertAgentMatchesReference(agent: Agent, reference: string): void {\n  const normalized = reference.trim().toLowerCase();\n  if (!normalized) throw new Error(\"Agent reference is required\");\n  const matches = [\n    agent.id,\n    agent.name,\n    typeof agent.urlKey === \"string\" ? agent.urlKey : null,\n  ].some((value) => value?.toLowerCase() === normalized);\n  if (!matches) {\n    throw new Error(\n      `Agent key belongs to ${agent.name} (${agent.id}), not '${reference}'. Use the matching agent or a board prompt.`,\n    );\n  }\n}\n\nfunction agentSummary(agent: Agent): PromptResult[\"agent\"] {\n  return {\n    id: agent.id,\n    name: agent.name,\n    urlKey: typeof agent.urlKey === \"string\" ? agent.urlKey : null,\n  };","sourceCodeStart":232,"sourceCodeEnd":268,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/client/prompt.ts#L232-L268","documentation":"`assertAgentMatchesReference` normalizes the expected agent reference and throws if it is empty after trimming. In practice the reference is `agentRef?.trim() || ctx.profile.agentId || me.id`, and `me.id` comes from a successfully authenticated `/api/agents/me`, so reaching an empty reference is rare and indicates the caller passed an explicit empty `--agent \"\"` and the profile has no `agentId`.","triggerScenarios":"Passing `--agent \"\"` (empty string) to agent-prompt while the profile also lacks an `agentId`; a programmatic caller of `runAgentPrompt` passing an empty/whitespace agentRef with a profile that has no agentId.","commonSituations":"Script that forwards an optional agent variable as `--agent \"$AGENT\"` where `$AGENT` is empty; misconfigured agent profile missing the `agentId` field.","solutions":["Omit `--agent` entirely to fall back to the profile agentId or the authenticated agent's own id","Pass a real agent ref (id, shortname, or url-key)","If automating, guard the variable: only add `--agent` when it is non-empty"],"exampleFix":"# before\npaperclipai agent prompt --agent \"\" \"do work\"\n# after\npaperclipai agent prompt \"do work\"","handlingStrategy":"validation","validationCode":"function resolveAgentRef(agentRef: string | undefined, profile: { agentId?: string }, meId: string): string {\n  const ref = agentRef?.trim() || profile.agentId || meId;\n  if (!ref.trim()) throw new Error(\"Agent reference is required\");\n  return ref;\n}","typeGuard":"function isNonEmptyRef(v: unknown): v is string {\n  return typeof v === \"string\" && v.trim().length > 0;\n}","tryCatchPattern":null,"preventionTips":["Omit --agent when it would be empty rather than passing `--agent \"\"`","Set profile.agentId so the fallback is meaningful","Guard optional variables before forwarding as --agent"],"tags":["cli","agent","validation","input"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}