paperclipai/paperclip · error · Error

Catalog team reference is required.

Error message

Catalog team reference is required.

What it means

Thrown by getCatalogTeam() when the catalog team reference is empty after trimming. It guards the GET /api/teams/catalog/ref?ref=... call used by `teams inspect`/`teams show` to fetch a single catalog team's metadata. Identical pattern to the skills catalog ref guard.

Source

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

    const installedTeam = installedByCatalogId.get(team.id);
    if (installedTeam) {
      installedByCatalogId.delete(team.id);
    }
    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 });

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Pass a non-empty catalog team id, key, or unique slug.
2. Browse first with `paperclipai teams browse` to find a valid ref.
3. Validate the ref is non-empty in your wrapper before invoking.

Example fix

// before
await run(["teams", "inspect", teamRefVar]);
// after
const ref = (teamRefVar ?? "").trim();
if (!ref) throw new Error("team ref required");
await run(["teams", "inspect", ref]);

const ref = (catalogRef ?? "").trim();
if (!ref) throw new Error("Catalog team ref is required.");
await run(["teams", "inspect", ref]);

function isValidTeamRef(ref: string | undefined): ref is string {
  return typeof ref === "string" && ref.trim().length > 0;
}

When it happens

Trigger: Running `paperclipai teams inspect <catalogRef>` with a blank argument (empty or whitespace), e.g. an unset variable expanded into the positional.

Common situations: Shell variable unset, script passing untrimmed input, or copy-paste of an empty cell from a spreadsheet.

Related errors

• Catalog skill reference is required.
• Company ID is required.
• Prompt text is required
• Agent reference is required
• 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/a97cc5e9c9e0f8d1. Report an issue: GitHub.