paperclipai/paperclip · error

Agent authentication failed

Error message

Agent authentication failed

What it means

The /api/agents/me lookup in runAgentPrompt failed or returned null, meaning the credential is not a valid/scoped agent key; a guard on agent self-identification.

Solutions

1. Check the agent API key/token for the profile and re-authenticate.

When it happens

Trigger: Thrown at cli/src/commands/client/prompt.ts:123 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

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

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

Appendix: 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 120ae5428f)