paperclipai/paperclip · error · Error

Agent not found: ${agentRef}

Error message

Agent not found: ${agentRef}

What it means

`runBoardPrompt` looks up the target agent via `GET /api/agents/<agentRef>?companyId=<id>`. If the API returns a falsy body (no matching agent), the function throws with the unresolved reference. The lookup is scoped by `companyId` from the resolved context, so an agent that exists in another company will not be found.

Source

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

    title: opts.title,
    wake: opts.wake !== false,
  });
  return result;
}

export async function runBoardPrompt(
  agentRef: string,
  prompt: string,
  opts: PromptOptions,
): Promise<PromptResult> {
  const ctx = resolveCommandContext(opts, { requireCompany: true });
  if (ctx.profile.persona && ctx.profile.persona !== "board") {
    throw new Error(`Profile '${ctx.profileName}' is persona=${ctx.profile.persona}; use an agent prompt command or a board profile.`);
  }
  const body = normalizePrompt(prompt);
  const query = new URLSearchParams({ companyId: ctx.companyId ?? "" });
  const agent = await ctx.api.get<Agent>(`${apiPath`/api/agents/${agentRef}`}?${query.toString()}`);
  if (!agent) throw new Error(`Agent not found: ${agentRef}`);

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

async function createOrCommentForAgent(input: {
  api: {
    apiBase: string;
    post<T>(path: string, body?: unknown): Promise<T | null>;
  };

View on GitHub (pinned to 67001ec6eb)

Solutions

1. List agents in the target company to copy the exact ref: `paperclipai agent list -C <companyId>`
2. Confirm the `--company-id` (or profile companyId / `PAPERCLIP_COMPANY_ID`) matches the company that owns the agent
3. Try the agent's stable ID instead of the shortname/url-key, which can be renamed

Example fix

# before
paperclipai board prompt --agent wrong-name "do work" -C comp-1
# after
paperclipai board prompt --agent agent_01H... "do work" -C comp-1

// Preflight: confirm the agent exists in the company before prompting
async function agentExists(api: { get<T>(p: string): Promise<T | null> }, ref: string, companyId: string): Promise<boolean> {
  const q = new URLSearchParams({ companyId });
  return Boolean(await api.get(`/api/agents/${encodeURIComponent(ref)}?${q}`));
}
if (!(await agentExists(ctx.api, agentRef, ctx.companyId ?? ""))) {
  throw new Error(`No agent '${agentRef}' in company '${ctx.companyId}'`);
}

try {
  const agent = await ctx.api.get(`/api/agents/${agentRef}?${query}`);
  if (!agent) throw new Error(`Agent not found: ${agentRef}`);
} catch (err) {
  console.error(`Agent lookup failed: ${err instanceof Error ? err.message : err}`);
  process.exit(1);
}

When it happens

Trigger: Passing an `--agent` value (ID, shortname, or url-key) that does not exist; passing a valid agent ref but with the wrong `--company-id` / profile companyId; the agent was deleted or the shortname/url-key changed.

Common situations: Typo in the agent shortname; copying an agent ID from one company into a command run against another; stale url-key after an agent was renamed; forgetting `-C` when the profile has no default company.

Related errors

• Agent not found: ${agentRef}
• --payload must be a JSON object
• Company ID is required. Pass --company-id, set PAPERCLIP_COM
• No company found by ID '${selector}'.
• No company found by shortname/prefix '${selector}'.

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