paperclipai/paperclip · error · Error

${name} exceeds the hard Paperclip ingestion cap of ${max} c

Error message

${name} exceeds the hard Paperclip ingestion cap of ${max} characters.

What it means

Thrown by assertRequestedCharacterLimit() when the value is a valid positive number but its floored value exceeds the hard cap (max) for that field. The cap is enforced per-field to bound Paperclip ingestion cost; the offending name and the cap are interpolated. This fires after the positivity check, so the value is finite and >= 1 but too large.

Source

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

    requireEnabledProfile: options.requireEnabledProfile,
  });
  if (!decision.allowed) throw new Error(decision.message);
  return decision.space;
}

function assertPaperclipSourceScopePayload(input: { projectId?: string | null; rootIssueId?: string | null }) {
  if (input.projectId && input.rootIssueId) {
    throw new Error("Paperclip source scope must specify either projectId or rootIssueId, not both.");
  }
}

function assertRequestedCharacterLimit(name: string, value: unknown, max: number) {
  if (value == null) return;
  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
    throw new Error(`${name} must be a positive number.`);
  }
  if (Math.floor(value) > max) {
    throw new Error(`${name} exceeds the hard Paperclip ingestion cap of ${max} characters.`);
  }
}

function stableSpaceId(input: { companyId: string; wikiId: string; slug: string }): string {
  const hex = createHash("md5")
    .update(`${input.companyId}:${input.wikiId}:${input.slug}`)
    .digest("hex");
  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-8${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
}

function normalizeLimit(value: unknown, fallback: number, max: number): number {
  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
  return Math.max(1, Math.min(max, Math.floor(value)));
}

function contentHash(contents: string): string {
  return createHash("sha256").update(contents, "utf8").digest("hex");
}

View on GitHub (pinned to 67001ec6eb)

Solutions

Reduce the requested value to be at or below the cap stated in the error message.
Clamp the value upstream: Math.min(Math.floor(value), cap) before calling — but confirm the clamped value is acceptable semantically.
Surface the cap in the UI so users do not request above it.

Example fix

// before
assertRequestedCharacterLimit("maxCharacters", 5_000_000, 250_000); // throws
// after
assertRequestedCharacterLimit("maxCharacters", 250_000, 250_000);

Defensive patterns

Strategy: validation

Validate before calling

function clampLimit(name: string, value: number | null | undefined, max: number): number | null {
  if (value == null) return null;
  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
    throw new Error(`${name} must be a positive number.`);
  }
  return Math.min(Math.floor(value), max);
}

Type guard

function withinCap(value: number, max: number): boolean {
  return Math.floor(value) <= max;
}

Try / catch

try {
  assertRequestedCharacterLimit("maxCharacters", value, MAX_CAP);
} catch (err) {
  if (err instanceof Error && err.message.includes("exceeds the hard Paperclip ingestion cap")) {
    value = MAX_CAP; // clamp and retry
  } else throw err;
}

Prevention

Clamp limit values to the documented cap before calling.
Surface the cap in the UI input's max attribute.
Confirm the cap matches the field you are setting (different fields may have different caps).

When it happens

Trigger: Passing maxCharacters above the ingestion cap (e.g. 200000 when the cap is much lower). Requesting an unlimited-ish number that breaches the safety ceiling.

Common situations: Caller assumes the hard cap matches some other system's limit. UI lets the user type a large number without a max attribute. Migration from an uncapped API to the capped one.

Related errors

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