paperclipai/paperclip · error · Error

Agent not found: ${agentRef}

Error message

Agent not found: ${agentRef}

What it means

Thrown by resolveAgent() when GET /api/agents/{agentRef}?companyId=... returns null/undefined. The resolver backs `skills agent list|sync|clear`, which need a concrete agent id to hit the agent skill endpoints. A null body means the server did not find an agent matching the ref within the company scope.

Source

Thrown at cli/src/commands/client/skills.ts:742

  const rows: Array<{ skill: CompanySkillReferenceTarget; audit: CompanySkillAuditResult }> = [];
  for (const skill of selected) {
    const audit = await ctx.api.post<CompanySkillAuditResult>(
      `/api/companies/${ctx.companyId}/skills/${encodeURIComponent(skill.id)}/audit`,
      {},
    );
    if (!audit) {
      throw new Error(`No audit result returned for skill ${skill.key}.`);
    }
    rows.push({ skill: toSkillReferenceTarget(skill), audit });
  }
  return rows;
}

async function resolveAgent(ctx: ResolvedClientContext, agentRef: string): Promise<Agent> {
  const params = new URLSearchParams({ companyId: ctx.companyId ?? "" });
  const agent = await ctx.api.get<Agent>(`/api/agents/${encodeURIComponent(agentRef)}?${params.toString()}`);
  if (!agent) {
    throw new Error(`Agent not found: ${agentRef}`);
  }
  return agent;
}

function printCompanySkillRows(rows: Array<CompanySkillListItem | CompanySkill>): void {
  if (rows.length === 0) {
    printOutput([], { json: false });
    return;
  }
  for (const row of rows) {
    console.log(
      formatInlineRecord({
        id: row.id,
        key: row.key,
        slug: row.slug,
        name: row.name,
        source: "sourceBadge" in row ? row.sourceBadge : row.sourceType,
        trust: row.trustLevel,

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Confirm the agent exists in the target company (e.g. via a company agents listing).
2. Use the full agent id rather than a shortname/url-key to avoid ambiguity.
3. Verify --company-id matches the company the agent belongs to.

Example fix

// before
await run(["skills", "agent", "list", shortName]);
// after
const agents = await runJson(["company", "agents", "--json"]); // or equivalent listing
const agent = agents.find(a => a.id === agentId);
await run(["skills", "agent", "list", agent.id]);

try {
  await run(["skills", "agent", "list", agentRef]);
} catch (err) {
  if (err instanceof Error && /Agent not found/.test(err.message)) {
    console.error(`${agentRef} not found in this company. Use the full agent id.`);
    process.exit(2);
  }
  throw err;
}

When it happens

Trigger: `paperclipai skills agent list <agentRef>`, `... sync <agentRef>`, or `... clear <agentRef>` where agentRef is a typo, belongs to another company, or is a shortname that is not unique/known to the server.

Common situations: Wrong company scope (PAPERCLIP_COMPANY_ID), archived agent, stale shortname after rename, or using an agent id from a different deployment.

Related errors

• Skill not found: ${reference}
• Agent not found: ${agentRef}
• At least one --skill value is required for skills agent sync
• Catalog skill not found: ${catalogRef}
• Ambiguous skill slug "${trimmed}". Use a skill ID or key ins

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