paperclipai/paperclip · error · Error

Agent authentication failed

Error message

Agent authentication failed

What it means

`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.

Source

Thrown at cli/src/commands/client/prompt.ts:123

          handleCommandError(err);
        }
      }),
    { includeCompany: false },
  );
}

export async function runAgentPrompt(
  agentRef: string | undefined,
  prompt: string,
  opts: PromptOptions,
): Promise<PromptResult> {
  const ctx = resolveCommandContext(opts);
  if (ctx.profile.persona && ctx.profile.persona !== "agent") {
    throw new Error(`Profile '${ctx.profileName}' is persona=${ctx.profile.persona}; use an agent profile or board prompt.`);
  }
  const body = normalizePrompt(prompt);
  const me = await ctx.api.get<Agent>("/api/agents/me");
  if (!me) throw new Error("Agent authentication failed");
  const expectedRef = agentRef?.trim() || ctx.profile.agentId || me.id;
  assertAgentMatchesReference(me, expectedRef);

  const result = await createOrCommentForAgent({
    api: ctx.api,
    actor: "agent",
    agent: me,
    companyId: me.companyId,
    prompt: body,
    issueId: opts.issue,
    title: opts.title,
    wake: opts.wake !== false,
  });
  return result;
}

export async function runBoardPrompt(
  agentRef: string,

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Verify an agent API key is resolvable: check `$PAPERCLIP_API_KEY` or the profile's `apiKeyEnvVarName`, or pass `--api-key <agentKey>`
2. 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>"`
3. If the key is stale, rotate/regenerate it server-side and update the env var or profile

Example fix

# before: env var unset or holds a board token
paperclipai agent prompt "do work"
# after
export PAPERCLIP_API_KEY=<agent-api-key>
paperclipai agent prompt "do work"

// Preflight: confirm /api/agents/me resolves before running the full prompt flow
async function agentMeResolves(api: { get<T>(p: string): Promise<T | null> }): Promise<boolean> {
  return Boolean(await api.get("/api/agents/me"));
}
if (!(await agentMeResolves(ctx.api))) {
  throw new Error("Agent credentials not accepted by /api/agents/me");
}

import type { Agent } from "@paperclipai/shared";
function isAgent(v: unknown): v is Agent {
  return typeof v === "object" && v !== null && typeof (v as Agent).id === "string";
}

try {
  const me = await ctx.api.get("/api/agents/me");
  if (!me) throw new Error("Agent authentication failed");
} catch (err) {
  console.error(`Agent auth check failed: ${err instanceof Error ? err.message : err}`);
  process.exit(1);
}

When it happens

Trigger: 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`.

Common situations: 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.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Agent key belongs to ${agent.name} (${agent.id}), not '${ref
• Environment variable ${opts.apiKeyEnv.trim()} is not set
• Request failed: ${response.status}
• CLI auth challenge was cancelled.
• CLI auth challenge expired before approval.

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