paperclipai/paperclip · error · Error

Paperclip ingestion profile must include at least one source

Error message

Paperclip ingestion profile must include at least one source scope before it can be enabled.

What it means

Thrown by validatePaperclipIngestionProfile() when the profile has enabled=true but sourceScopes is empty. An enabled profile must scope at least one Paperclip source; otherwise ingestion would have nothing to pull. This runs after the policy check, so the space itself is eligible. (Same code at line 992; error 477 is the duplicate occurrence.)

Source

Thrown at packages/plugins/plugin-llm-wiki/src/wiki/core.ts:992

    }
  }
  return overlaps;
}

async function validatePaperclipIngestionProfile(ctx: PluginContext, input: {
  companyId: string;
  space: WikiSpace;
  profile: PaperclipIngestionProfileV1;
}) {
  const policy = evaluatePaperclipProfilePolicy({
    space: input.space,
    profile: input.profile,
    purpose: "profile_update",
    requireEnabledProfile: input.profile.enabled && input.space.slug !== DEFAULT_SPACE_SLUG,
  });
  if (!policy.allowed) throw new Error(policy.message);
  if (input.profile.enabled && input.profile.sourceScopes.length === 0) {
    throw new Error("Paperclip ingestion profile must include at least one source scope before it can be enabled.");
  }
  if (input.profile.sourceScopes.length > MAX_PAPERCLIP_INGESTION_PROFILE_SOURCE_COUNT) {
    throw new Error(`Paperclip ingestion profile sources exceed the hard cap of ${MAX_PAPERCLIP_INGESTION_PROFILE_SOURCE_COUNT}.`);
  }
  for (const scope of input.profile.sourceScopes) {
    if (scope.kind === "company_all" && input.space.slug !== DEFAULT_SPACE_SLUG) {
      throw new Error("Everything in the company is only available on the default wiki space.");
    }
    if (scope.kind === "selected_projects") {
      if (scope.projectIds.length > MAX_PAPERCLIP_PROFILE_SELECTED_PROJECTS) {
        throw new Error(`selected_projects exceeds the hard cap of ${MAX_PAPERCLIP_PROFILE_SELECTED_PROJECTS}.`);
      }
      for (const projectId of scope.projectIds) {
        const project = await ctx.projects.get(projectId, input.companyId);
        if (!project) throw new Error(`Project belongs to another company or does not exist: ${projectId}`);
      }
    }
    if (scope.kind === "root_issues") {

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Add at least one source scope (selected_projects, root_issues, or company_all on default space) before enabling.
2. If not ready to enable, set enabled: false until scopes are configured.
3. Validate in the UI that the Enable action is disabled while sourceScopes is empty.

Example fix

// before
profile = { enabled: true, sourceScopes: [], ... };
// after
profile = { enabled: true, sourceScopes: [{ kind: "company_all" }], ... }; // default space only
// or:
profile = { enabled: false, sourceScopes: [], ... };

function assertEnabledHasScopes(profile: { enabled: boolean; sourceScopes: unknown[] }) {
  if (profile.enabled && profile.sourceScopes.length === 0) {
    throw new Error("Add at least one source scope before enabling the profile.");
  }
}

function canEnableProfile(profile: { sourceScopes: unknown[] }): boolean {
  return profile.sourceScopes.length > 0;
}

try {
  await validatePaperclipIngestionProfile(ctx, { companyId, space, profile });
} catch (err) {
  if (err instanceof Error && err.message.includes("must include at least one source scope")) {
    profile.sourceScopes.push({ kind: "selected_projects", projectIds: ["p1"] }); // then retry
  } else throw err;
}

When it happens

Trigger: Submitting a profile update with enabled: true and sourceScopes: []. Saving a partially-configured profile before adding any scope.

Common situations: UI lets the user flip Enable before adding scopes. API client that defaults sourceScopes to []. Migration that lost scope entries.

Related errors

• Paperclip source scope must specify either projectId or root
• ${name} must be a positive number.
• ${name} exceeds the hard Paperclip ingestion cap of ${max} c
• ${policy.message}
• Paperclip ingestion profile sources exceed the hard cap of $

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