paperclipai/paperclip · error · Error

Failed to create board token

Error message

Failed to create board token

What it means

Thrown in connectWizard() (board persona branch) after POST /api/board-api-keys returns null. The board key creation endpoint is expected to return a CreatedBoardKey object (with id, name, createdAt, plaintext key); null means the server returned 204/empty body. Without the key material the wizard cannot persist a profile, so it aborts.

Source

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

    command: "paperclipai connect",
  });
  const boardApi = new PaperclipApiClient({ apiBase, apiKey: boardLogin.token });
  const companies = (await boardApi.get<Company[]>("/api/companies")) ?? [];

  const persona = await choosePersona(opts.persona);
  const profileName = opts.profile?.trim() || await askProfileName(resolvedProfile.name);
  const apiKeyEnvVarName = opts.apiKeyEnvVarName?.trim() || "PAPERCLIP_API_KEY";

  if (persona === "board") {
    const company = await chooseCompany(companies, opts.companyId ?? resolvedProfile.profile.companyId, {
      optional: true,
    });
    const tokenName = opts.tokenName?.trim() || `cli-board-${new Date().toISOString()}`;
    const key = await boardApi.post<CreatedBoardKey>("/api/board-api-keys", createBoardApiKeySchema.parse({
      name: tokenName,
      requestedCompanyId: company?.id ?? null,
    }));
    if (!key) throw new Error("Failed to create board token");
    upsertProfile(profileName, {
      apiBase,
      companyId: company?.id,
      persona: "board",
      agentId: "",
      agentName: "",
      apiKeyEnvVarName,
      tokenName: key.name,
      tokenId: key.id,
      tokenCreatedAt: key.createdAt,
    }, opts.context);
    setCurrentProfile(profileName, opts.context);
    p.outro(pc.green(`Connected profile '${profileName}' as board.`));
    return {
      ok: true,
      profile: profileName,
      persona: "board",
      apiBase,

View on GitHub (pinned to 67001ec6eb)

Solutions

  1. Verify the endpoint returns a body: `curl -i -X POST <api-base>/api/board-api-keys -H 'authorization: Bearer <token>' -d '{"name":"test"}'`.
  2. Confirm the server version implements board-api-keys creation.
  3. Check that the board token used has key-management privilege.
  4. Inspect server logs for an exception in the key-creation handler.
Defensive patterns

Strategy: try-catch

Validate before calling

// Probe the board-api-keys endpoint returns a body before relying on the wizard.
async function canCreateBoardKey(api: { post: (p: string, b?: unknown) => Promise<unknown> }): Promise<boolean> {
  try {
    const k = await api.post("/api/board-api-keys", { name: "probe" });
    return k != null && typeof (k as any).id === "string";
  } catch { return false; }
}

Type guard

import type { CreatedBoardKey } from "@paperclipai/shared";

function isCreatedBoardKey(v: unknown): v is CreatedBoardKey {
  return !!v && typeof v === "object"
    && typeof (v as CreatedBoardKey).id === "string"
    && typeof (v as CreatedBoardKey).name === "string";
}

Try / catch

try {
  const key = await boardApi.post<CreatedBoardKey>("/api/board-api-keys", payload);
  if (!isCreatedBoardKey(key)) throw new Error("Board key creation returned no key; check server version.");
} catch (err) {
  throw err;
}

Prevention

When it happens

Trigger: The board-api-keys endpoint responds 204 No Content or an empty body; the endpoint is unimplemented on the targeted server version; a proxy strips the response; the create partially succeeded server-side but returned nothing.

Common situations: Server version mismatch (older server without board key creation); reverse proxy truncating the response; transient server error yielding 204; board token used to create the key lacks sufficient privilege and the server returns empty.

Related errors

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