{"record":{"id":"2682e10c67c0424c","repo":"paperclipai/paperclip","slug":"failed-to-create-agent-api-key","errorCode":null,"errorMessage":"Failed to create agent API key","messagePattern":"Failed to create agent API key","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/commands/client/token.ts","lineNumber":78,"sourceCode":"\nexport function registerTokenCommands(program: Command): void {\n  const token = program.command(\"token\").description(\"Manage Paperclip API tokens\");\n  const agent = token.command(\"agent\").description(\"Manage agent API keys\");\n\n  addCommonClientOptions(\n    agent\n      .command(\"create\")\n      .description(\"Create an agent API key\")\n      .requiredOption(\"-C, --company-id <id>\", \"Company ID\")\n      .requiredOption(\"--agent <agent>\", \"Agent ID, shortname, or unambiguous name\")\n      .option(\"--name <name>\", \"API key label\", \"cli-agent\")\n      .action(async (opts: AgentTokenOptions) => {\n        try {\n          const ctx = resolveCommandContext(opts, { requireCompany: true });\n          const agentRow = await resolveAgent(ctx.api, ctx.companyId ?? \"\", opts.agent ?? \"\");\n          const payload = createAgentKeySchema.parse({ name: opts.name });\n          const key = await ctx.api.post<CreatedAgentKey>(apiPath`/api/agents/${agentRow.id}/keys`, payload);\n          if (!key) throw new Error(\"Failed to create agent API key\");\n          printOutput(\n            {\n              agentId: agentRow.id,\n              agentName: agentRow.name,\n              companyId: agentRow.companyId,\n              key,\n            },\n            { json: ctx.json },\n          );\n        } catch (err) {\n          handleCommandError(err);\n        }\n      }),\n    { includeCompany: false },\n  );\n\n  addCommonClientOptions(\n    agent","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/client/token.ts#L60-L96","documentation":"Thrown by the `agent create` action in token.ts when ctx.api.post to /api/agents/{id}/keys returns a falsy value (null/undefined). The POST must return a CreatedAgentKey object; an empty 2xx body, a proxy that stripped the body, or an API client that resolves null on parse failure trips this guard.","triggerScenarios":"Calling `paperclipai ... token agent create --company-id X --agent Y` where the server returns 200/201 with an empty body, or the API client's post helper resolves null on a malformed JSON response.","commonSituations":"Misconfigured API base URL hitting a different service, a reverse proxy that rewrites the response, an outdated CLI talking to an API version that changed the key-creation response shape, or a network layer returning null on JSON parse failure.","solutions":["Verify the server is the expected Paperclip version for this CLI: compare /api/health and the CLI version.","Hit the endpoint directly with curl -X POST /api/agents/{id}/keys to inspect the raw response body.","Check API_BASE / base URL resolution so the post targets the Paperclip API and not a gateway returning empty.","Inspect CLI verbose/debug logs for the raw response status and body."],"exampleFix":"// before: server returns {} or empty 2xx\n// fix server handler to return the created key object\nres.status(201).json({ id, key, name, agentId });","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isCreatedAgentKey(value: unknown): value is CreatedAgentKey {\n  return !!value && typeof value === \"object\" && \"key\" in value && typeof (value as any).key === \"string\";\n}","tryCatchPattern":"try {\n  const key = await ctx.api.post<CreatedAgentKey>(path, payload);\n  if (!isCreatedAgentKey(key)) throw new Error(\"Server returned no key body\");\n  // use key\n} catch (err) {\n  handleCommandError(err);\n}","preventionTips":["Keep CLI and server versions aligned so the response shape matches.","Verify the API base URL points at Paperclip, not a proxy returning empty.","Hit POST /api/agents/{id}/keys with curl first to confirm a non-empty body."],"tags":["cli","agent-keys","api-contract","null-response"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}