paperclipai/paperclip · error · Error

Catalog team not found: ${catalogRef}

Error message

Catalog team not found: ${catalogRef}

What it means

Thrown by getCatalogTeam() when GET /api/teams/catalog/ref?ref=... returns null/undefined for a non-empty ref. The server could not resolve the catalog team identifier (id, key, or slug) in the app-shipped teams catalog.

Source

Thrown at cli/src/commands/client/teams.ts:328

    return buildCatalogTeamStatusRow(team, installedTeam ?? null);
  });

  for (const installedTeam of installedByCatalogId.values()) {
    if (installedTeam.present) continue;
    rows.push(buildMissingInstalledTeamStatusRow(installedTeam));
  }

  return rows;
}

async function getCatalogTeam(ctx: ResolvedClientContext, catalogRef: string): Promise<CatalogTeam> {
  const ref = catalogRef.trim();
  if (!ref) {
    throw new Error("Catalog team reference is required.");
  }
  const detail = await ctx.api.get<CatalogTeam>(`/api/teams/catalog/ref?ref=${encodeURIComponent(ref)}`);
  if (!detail) {
    throw new Error(`Catalog team not found: ${catalogRef}`);
  }
  return detail;
}

async function getCatalogTeamFile(
  ctx: ResolvedClientContext,
  catalogRef: string,
  filePath: string,
): Promise<{ content: string } | null> {
  const ref = catalogRef.trim();
  const path = filePath.trim();
  if (!ref) throw new Error("Catalog team reference is required.");
  if (!path) throw new Error("Catalog team file path is required.");
  const params = new URLSearchParams({ ref, path });
  return ctx.api.get(`/api/teams/catalog/ref/files?${params.toString()}`);
}

function catalogTeamCompanyPath(companyId: string | undefined, catalogRef: string, action: "preview" | "install") {

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Run `paperclipai teams browse` and copy the exact id/key.
2. Confirm you are hitting the expected API base.
3. If the team was renamed, search by category/query (`--query`).

Example fix

# before
paperclipai teams inspect old-team-key
# after
paperclipai teams browse --query <word>
paperclipai teams inspect <id-from-browse>

try {
  await run(["teams", "inspect", ref]);
} catch (err) {
  if (err instanceof Error && /Catalog team not found/.test(err.message)) {
    console.error(`${ref} not in catalog. Run \`teams browse\` first.`);
    process.exit(2);
  }
  throw err;
}

When it happens

Trigger: `paperclipai teams inspect <ref>` with a typo, a ref from a different Paperclip version/deployment, or a value that is actually a skill rather than a team.

Common situations: Catalog refresh removed/renamed a team, staging-vs-prod catalog mismatch, or confusing the skills catalog ref with the teams catalog ref.

Related errors

• Catalog skill not found: ${catalogRef}
• Company ID is required.
• Catalog team reference is required.
• Approval request failed.
• Agent not found: ${agentRef}

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