{"record":{"id":"aa4430e1f438242d","repo":"paperclipai/paperclip","slug":"agent-authentication-failed","errorCode":null,"errorMessage":"Agent authentication failed","messagePattern":"Agent authentication failed","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/commands/client/prompt.ts","lineNumber":123,"sourceCode":"          handleCommandError(err);\n        }\n      }),\n    { includeCompany: false },\n  );\n}\n\nexport async function runAgentPrompt(\n  agentRef: string | undefined,\n  prompt: string,\n  opts: PromptOptions,\n): Promise<PromptResult> {\n  const ctx = resolveCommandContext(opts);\n  if (ctx.profile.persona && ctx.profile.persona !== \"agent\") {\n    throw new Error(`Profile '${ctx.profileName}' is persona=${ctx.profile.persona}; use an agent profile or board prompt.`);\n  }\n  const body = normalizePrompt(prompt);\n  const me = await ctx.api.get<Agent>(\"/api/agents/me\");\n  if (!me) throw new Error(\"Agent authentication failed\");\n  const expectedRef = agentRef?.trim() || ctx.profile.agentId || me.id;\n  assertAgentMatchesReference(me, expectedRef);\n\n  const result = await createOrCommentForAgent({\n    api: ctx.api,\n    actor: \"agent\",\n    agent: me,\n    companyId: me.companyId,\n    prompt: body,\n    issueId: opts.issue,\n    title: opts.title,\n    wake: opts.wake !== false,\n  });\n  return result;\n}\n\nexport async function runBoardPrompt(\n  agentRef: string,","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/client/prompt.ts#L105-L141","documentation":"`runAgentPrompt` calls `GET /api/agents/me` to load the authenticated agent. That endpoint resolves the caller from the bearer API key; if it returns a falsy body (no agent for the provided credentials), the function throws. This is an authentication/identity failure: the request reached the API but the server did not recognize the caller as an agent.","triggerScenarios":"The resolved API key is missing, expired, revoked, or belongs to a board operator rather than an agent; the `--api-base` points at the wrong server; the `--api-key-env` variable resolved but its value is a board token. The client's auth source can be `explicit`, `env`, `profile_env`, `stored_board`, or `none`.","commonSituations":"Agent profile whose `apiKeyEnvVarName` points at an unset or stale env var; using a board stored credential where an agent key is required; pointing at the wrong apiBase after a server move; key rotated server-side but the local env still holds the old value.","solutions":["Verify an agent API key is resolvable: check `$PAPERCLIP_API_KEY` or the profile's `apiKeyEnvVarName`, or pass `--api-key <agentKey>`","Confirm `--api-base` (or `PAPERCLIP_API_URL`) points at the running Paperclip API and `/api/agents/me` returns the agent with `curl -H \"Authorization: Bearer <key>\"`","If the key is stale, rotate/regenerate it server-side and update the env var or profile"],"exampleFix":"# before: env var unset or holds a board token\npaperclipai agent prompt \"do work\"\n# after\nexport PAPERCLIP_API_KEY=<agent-api-key>\npaperclipai agent prompt \"do work\"","handlingStrategy":"try-catch","validationCode":"// Preflight: confirm /api/agents/me resolves before running the full prompt flow\nasync function agentMeResolves(api: { get<T>(p: string): Promise<T | null> }): Promise<boolean> {\n  return Boolean(await api.get(\"/api/agents/me\"));\n}\nif (!(await agentMeResolves(ctx.api))) {\n  throw new Error(\"Agent credentials not accepted by /api/agents/me\");\n}","typeGuard":"import type { Agent } from \"@paperclipai/shared\";\nfunction isAgent(v: unknown): v is Agent {\n  return typeof v === \"object\" && v !== null && typeof (v as Agent).id === \"string\";\n}","tryCatchPattern":"try {\n  const me = await ctx.api.get(\"/api/agents/me\");\n  if (!me) throw new Error(\"Agent authentication failed\");\n} catch (err) {\n  console.error(`Agent auth check failed: ${err instanceof Error ? err.message : err}`);\n  process.exit(1);\n}","preventionTips":["Verify the agent API key works with a curl preflight against /api/agents/me","Keep agent keys in a dedicated env var referenced by the profile's apiKeyEnvVarName","Rotate keys server-side and update the env var atomically"],"tags":["cli","auth","agent","api","credentials"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}