paperclipai/paperclip · error · Error

Failed to create agent token

Error message

Failed to create agent token

What it means

Thrown when POST /api/agents/{agent.id}/keys returns a falsy value. The API client's post<T> unwraps to undefined when the server response body is empty or unparseable, so the new key cannot be persisted to the profile.

Source

Thrown at cli/src/commands/client/connect.ts:132

      profile: profileName,
      persona: "board",
      apiBase,
      companyId: company?.id ?? null,
      key: publicKeyResult(key),
      exports: buildExports({ apiBase, companyId: company?.id, agentId: undefined, envName: apiKeyEnvVarName, token: key.token }),
    };
  }

  const company = await chooseCompany(companies, opts.companyId ?? resolvedProfile.profile.companyId, {
    optional: false,
  });
  if (!company) throw new Error("Company is required for agent profiles");
  const agents = (await boardApi.get<Agent[]>(apiPath`/api/companies/${company.id}/agents`)) ?? [];
  if (agents.length === 0) throw new Error(`Company '${company.name}' has no agents to connect.`);
  const agent = await chooseAgent(agents, resolvedProfile.profile.agentId);
  const tokenName = opts.tokenName?.trim() || `cli-agent-${new Date().toISOString()}`;
  const key = await boardApi.post<CreatedAgentKey>(apiPath`/api/agents/${agent.id}/keys`, createAgentKeySchema.parse({ name: tokenName }));
  if (!key) throw new Error("Failed to create agent token");
  upsertProfile(profileName, {
    apiBase,
    companyId: company.id,
    persona: "agent",
    agentId: agent.id,
    agentName: agent.name,
    apiKeyEnvVarName,
    tokenName: key.name,
    tokenId: key.id,
    tokenCreatedAt: key.createdAt,
  }, opts.context);
  setCurrentProfile(profileName, opts.context);
  p.outro(pc.green(`Connected profile '${profileName}' as ${agent.name}.`));
  return {
    ok: true,
    profile: profileName,
    persona: "agent",
    apiBase,

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Check the server logs for the /api/agents/{id}/keys request and confirm a CreatedAgentKey body is returned.
2. Retry connect; if it persists, hit the endpoint with curl using the board token to inspect the raw response.
3. Verify apiBase points at a healthy Paperclip API instance.

const isCreatedAgentKey = (v: unknown): v is CreatedAgentKey =>
  !!v && typeof v === 'object' && typeof (v as any).token === 'string' && typeof (v as any).id === 'string';

try {
  const key = await boardApi.post<CreatedAgentKey>(url, body);
  if (!isCreatedAgentKey(key)) throw new Error('Failed to create agent token');
} catch (err) {
  // Surface server error, then retry once or fall back to manual key creation.
  console.error('Agent key creation failed:', err instanceof Error ? err.message : err);
  throw err;
}

When it happens

Trigger: createAgentKeySchema.parse({name}) is POSTed to /api/agents/{id}/keys and the client resolves to undefined/null.

Common situations: Proxy or middleware stripping the response body; server-side error returning 2xx with no body; transient network/auth issue that the client silently swallowed.

Related errors

• `paperclipai connect` is interactive. For scripts, pass --ap
• Failed to create board token
• Company is required for agent profiles
• Company '${company.name}' has no agents to connect.
• Profile name is required

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/b41b9133ea0ea8a8. Report an issue: GitHub.