paperclipai/paperclip · error · Error

Agent key belongs to ${agent.name} (${agent.id}), not '${ref

Error message

Agent key belongs to ${agent.name} (${agent.id}), not '${reference}'. Use the matching agent or a board prompt.

What it means

`assertAgentMatchesReference` compares the authenticated agent (`me` from `/api/agents/me`) against the requested reference by matching `me.id`, `me.name`, or `me.urlKey` (case-insensitive). If none match, it throws, naming the key's true owner. This prevents using one agent's API key to impersonate or target a different agent in an agent-prompt (which must be self-directed).

Source

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

  if (!normalized) throw new Error("Prompt text is required");
  return normalized;
}

function defaultPromptTitle(prompt: string): string {
  const firstLine = prompt.split(/\r?\n/).map((line) => line.trim()).find(Boolean) ?? "Prompt handoff";
  return firstLine.length > 100 ? `${firstLine.slice(0, 97)}...` : firstLine;
}

function assertAgentMatchesReference(agent: Agent, reference: string): void {
  const normalized = reference.trim().toLowerCase();
  if (!normalized) throw new Error("Agent reference is required");
  const matches = [
    agent.id,
    agent.name,
    typeof agent.urlKey === "string" ? agent.urlKey : null,
  ].some((value) => value?.toLowerCase() === normalized);
  if (!matches) {
    throw new Error(
      `Agent key belongs to ${agent.name} (${agent.id}), not '${reference}'. Use the matching agent or a board prompt.`,
    );
  }
}

function agentSummary(agent: Agent): PromptResult["agent"] {
  return {
    id: agent.id,
    name: agent.name,
    urlKey: typeof agent.urlKey === "string" ? agent.urlKey : null,
  };
}

function readApiKeyEnvOption(opts: PromptOptions): string | undefined {
  if (!opts.apiKeyEnv?.trim()) return undefined;
  const value = process.env[opts.apiKeyEnv.trim()]?.trim();
  if (!value) throw new Error(`Environment variable ${opts.apiKeyEnv.trim()} is not set`);
  return value;

View on GitHub (pinned to 67001ec6eb)

Solutions

Use an agent prompt without `--agent` so it targets the authenticated agent (`me.id`)
Provide the `--agent` ref that matches the API key's owner (id/shortname/url-key of the same agent)
If you need to target a different agent, use `board prompt --agent <ref>` with board credentials instead

Example fix

# before: key belongs to agent A, targeting agent B
paperclipai agent prompt --agent agent-b "do work"
# after
paperclipai agent prompt "do work"   # targets the authenticated agent
# or, to target a different agent:
paperclipai board prompt --agent agent-b "do work"

Defensive patterns

Strategy: validation

Validate before calling

function agentMatchesRef(agent: { id: string; name: string; urlKey?: string | null }, ref: string): boolean {
  const n = ref.trim().toLowerCase();
  if (!n) return false;
  return [agent.id, agent.name, agent.urlKey].some((v) => typeof v === "string" && v.toLowerCase() === n);
}
if (!agentMatchesRef(me, expectedRef)) {
  throw new Error(`Key owner ${me.name} (${me.id}) does not match ref '${expectedRef}'`);
}

Prevention

For agent prompts, omit --agent so it self-targets the authenticated agent
Keep one API key per agent and pair it with the matching profile.agentId
Use board prompt (board credentials) to target a different agent

When it happens

Trigger: Authenticating as agent A (via `--api-key` or profile env) but passing `--agent agentB` (or a profile.agentId pointing at agentB) to `agent-prompt`/`agent prompt`. The key owner and the requested target disagree.

Common situations: Reusing a shared CI key across multiple agents but forgetting to update the `--agent` ref; profile.agentId stale after the agent identity changed; copy-pasting an agent ref from one context into a command run with another agent's key.

Related errors

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