paperclipai/paperclip · error

Agent reference is required

Error message

Agent reference is required

What it means

assertAgentMatchesReference got an empty normalized reference, so there is no agent identity to compare against the API-key owner.

Solutions

1. Provide an agent reference (name or ID).

When it happens

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

Common situations: See trigger scenarios.

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

Appendix: source

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

    reason,
    payload: { issueId },
  });
}

function normalizePrompt(prompt: string): string {
  const normalized = prompt.trim();
  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,
  };

View on GitHub (pinned to 120ae5428f)