paperclipai/paperclip · error · Error

runId is required

Error message

runId is required

What it means

Thrown by the record-paperclip-distillation-outcome worker action after status validation when params.runId is missing or blank. runId is the correlation key for the distillation run; without it the outcome cannot be matched to its cursor/run record.

Source

Thrown at packages/plugins/plugin-llm-wiki/src/worker.ts:555

        maxCharacters: typeof params.maxCharacters === "number" ? params.maxCharacters : null,
        maxCharactersPerSource: typeof params.maxCharactersPerSource === "number" ? params.maxCharactersPerSource : null,
        backfillStartAt: stringField(params.backfillStartAt),
        backfillEndAt: stringField(params.backfillEndAt),
        routineRun: params.routineRun === true,
        includeComments: params.includeComments !== false,
        includeDocuments: params.includeDocuments !== false,
        workItemId: stringField(params.workItemId),
        operationIssueId: stringField(params.operationIssueId),
      });
    });

    ctx.actions.register("record-paperclip-distillation-outcome", async (params) => {
      const status = stringField(params.status);
      if (status !== "succeeded" && status !== "failed" && status !== "review_required") {
        throw new Error("status must be succeeded, failed, or review_required");
      }
      const runId = stringField(params.runId);
      if (!runId) throw new Error("runId is required");
      return recordPaperclipDistillationOutcome(ctx, {
        companyId: readCompanyIdFromParams(params),
        wikiId: stringField(params.wikiId),
        spaceSlug: stringField(params.spaceSlug),
        runId,
        cursorId: stringField(params.cursorId),
        status,
        sourceHash: stringField(params.sourceHash),
        sourceWindowEnd: stringField(params.sourceWindowEnd),
        warning: stringField(params.warning),
        costCents: typeof params.costCents === "number" ? params.costCents : null,
        retryCount: typeof params.retryCount === "number" ? params.retryCount : null,
      });
    });

    ctx.actions.register("distill-paperclip-project-page", async (params) => {
      return distillPaperclipProjectPage(ctx, {
        companyId: readCompanyIdFromParams(params),

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Always pass runId (the run's identifier from when it was queued/started).
2. Check param key spelling (camelCase runId).
3. Generate and persist a runId at queue time so it is available at outcome time.

Example fix

// before
record(..., { status: 'succeeded' });
// after
record(..., { status: 'succeeded', runId });

function assertRunId(value: unknown) {
  if (typeof value !== 'string' || !value.trim()) throw new Error('runId is required');
}

function isNonBlankString(value: unknown): value is string {
  return typeof value === 'string' && value.trim().length > 0;
}

When it happens

Trigger: Calling record-paperclip-distillation-outcome with a valid status but runId absent, empty, or whitespace-only (stringField returns null).

Common situations: The run handler forgot to propagate runId; the param was keyed 'run_id' instead of 'runId'; the run was triggered outside the normal queue and never assigned an id.

Related errors

• Paperclip ingestion fan-out exceeds the hard cap of ${MAX_PA
• Backfill work items must target a projectId or rootIssueId;
• projectId or rootIssueId is required
• status must be succeeded, failed, or review_required
• projectId or rootIssueId is required

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