paperclipai/paperclip · error · Error

Agent not found: ${agentRef}

Error message

Agent not found: ${agentRef}

What it means

Thrown by the `paperclipai agent wake` action when the GET /api/agents/{agentRef} (with optional ?companyId=) returned a falsy value. The CLI resolves the agent by ref (id or slug) before issuing POST /api/agents/{id}/wakeup, and aborts if the lookup yielded nothing. Note the agent lookup is company-scoped when --company-id is supplied.

Source

Thrown at cli/src/commands/client/agent.ts:744

  addCommonClientOptions(
    agent
      .command("wake")
      .description("Request a heartbeat wakeup for an agent")
      .argument("<agentRef>", "Agent ID or shortname/url-key")
      .option("-C, --company-id <id>", "Company ID for shortname/url-key lookup")
      .option("--source <source>", "Invocation source (timer, assignment, on_demand, automation)", "on_demand")
      .option("--trigger <trigger>", "Trigger detail (manual, ping, callback, system)", "manual")
      .option("--reason <text>", "Wakeup reason")
      .option("--payload <json>", "JSON object payload")
      .option("--idempotency-key <key>", "Wakeup idempotency key")
      .option("--force-fresh-session", "Request a fresh adapter session")
      .action(async (agentRef: string, opts: AgentWakeOptions) => {
        try {
          const ctx = resolveCommandContext(opts);
          const query = opts.companyId ? `?${new URLSearchParams({ companyId: opts.companyId }).toString()}` : "";
          const agentRow = await ctx.api.get<Agent>(`${apiPath`/api/agents/${agentRef}`}${query}`);
          if (!agentRow) {
            throw new Error(`Agent not found: ${agentRef}`);
          }
          const payload = wakeAgentSchema.parse({
            source: opts.source,
            triggerDetail: opts.trigger,
            reason: opts.reason,
            payload: parseJsonObject(opts.payload),
            idempotencyKey: opts.idempotencyKey,
            forceFreshSession: Boolean(opts.forceFreshSession),
          });
          const result = await ctx.api.post<AgentWakeupResponse>(apiPath`/api/agents/${agentRow.id}/wakeup`, payload);
          printOutput(result, { json: ctx.json });
        } catch (err) {
          handleCommandError(err);
        }
      }),
    { includeCompany: false },
  );

View on GitHub (pinned to 67001ec6eb)

Solutions

1. List agents to confirm the ref: `paperclipai agent list --company-id <co>`.
2. Pass the correct company: `paperclipai agent wake <ref> --company-id <co>`.
3. Confirm you are pointed at the right instance: check --api-base / context profile.
4. Use the agent's canonical id (starts with agt_) rather than a slug if slugs collide.

Example fix

// before
paperclipai agent wake my-agent
// after
paperclipai agent wake agt_abc123 --company-id cmp_xyz

import { PaperclipApiClient } from '../../client/http.js';
async function ensureAgent(api: PaperclipApiClient, ref: string, companyId?: string) {
  const q = companyId ? `?${new URLSearchParams({ companyId }).toString()}` : '';
  const row = await api.get(`/api/agents/${encodeURIComponent(ref)}${q}`).catch(() => null);
  if (!row) throw new Error(`No agent matching '${ref}'${companyId ? ` in company ${companyId}` : ''}`);
  return row;
}

function isAgentRow(v: unknown): v is { id: string } {
  return typeof v === 'object' && v !== null && typeof (v as any).id === 'string';
}

try { await wake(agentRef, opts); }
catch (err) {
  const msg = err instanceof Error ? err.message : '';
  if (msg.startsWith('Agent not found:')) {
    console.error(`Unknown agent '${agentRef}'. Run: paperclipai agent list --company-id ${opts.companyId ?? ''}`);
    process.exit(2);
  }
  throw err;
}

When it happens

Trigger: agentRef does not match any agent id/slug. The agent exists but belongs to a different company than the resolved --company-id (or the default company in context). The API returned 404-shaped null (the client coerces not-found to undefined/null). Wrong apiBase pointing at an environment where the agent does not exist.

Common situations: Typo in the agent id/slug. Copy-pasting an agent ref from one Paperclip instance into a CLI pointed at another. Forgetting to set --company-id / PAPERCLIP_COMPANY_ID when the agent lives in a non-default company. Agent was deleted before the wake call.

Related errors

• Agent not found: ${agentRef}
• Agent not found: ${agentRef}
• Refusing to delete without --yes
• Failed to create API key
• --payload must be a JSON object

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