paperclipai/paperclip · error · Error

Agent reference is required

Error message

Agent reference is required

What it means

`assertAgentMatchesReference` normalizes the expected agent reference and throws if it is empty after trimming. In practice the reference is `agentRef?.trim() || ctx.profile.agentId || me.id`, and `me.id` comes from a successfully authenticated `/api/agents/me`, so reaching an empty reference is rare and indicates the caller passed an explicit empty `--agent ""` and the profile has no `agentId`.

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 67001ec6eb)

Solutions

1. Omit `--agent` entirely to fall back to the profile agentId or the authenticated agent's own id
2. Pass a real agent ref (id, shortname, or url-key)
3. If automating, guard the variable: only add `--agent` when it is non-empty

Example fix

# before
paperclipai agent prompt --agent "" "do work"
# after
paperclipai agent prompt "do work"

function resolveAgentRef(agentRef: string | undefined, profile: { agentId?: string }, meId: string): string {
  const ref = agentRef?.trim() || profile.agentId || meId;
  if (!ref.trim()) throw new Error("Agent reference is required");
  return ref;
}

function isNonEmptyRef(v: unknown): v is string {
  return typeof v === "string" && v.trim().length > 0;
}

When it happens

Trigger: Passing `--agent ""` (empty string) to agent-prompt while the profile also lacks an `agentId`; a programmatic caller of `runAgentPrompt` passing an empty/whitespace agentRef with a profile that has no agentId.

Common situations: Script that forwards an optional agent variable as `--agent "$AGENT"` where `$AGENT` is empty; misconfigured agent profile missing the `agentId` field.

Related errors

• --payload must be a JSON object
• Agent not found: ${agentRef}
• Prompt text is required
• Agent key belongs to ${agent.name} (${agent.id}), not '${ref
• Invalid --include value. Use one or more of: company,agents,

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