paperclipai/paperclip · error · WorkspaceGitScanError

workspace_git_scan_saturated

workspace_git_scan_saturated

Error message

Changed files are temporarily unavailable because the Git scan queue is full

What it means

Git scan scheduler saturation: active scans are at concurrency AND the wait queue is at capacity, so the request is refused (warned as 'saturated') instead of unboundedly growing the queue. Callers should back off and retry — the queue drains as in-flight scans finish; sustained saturation means concurrency/queue capacity needs tuning.

Source

Thrown at server/src/services/workspace-git-operation-scheduler.ts:536

    const existing = this.inFlight.get(key);
    if (existing) {
      existing.joinCount += 1;
      this.totals.singleFlightJoins += 1;
      return this.addWaiter(existing, input.signal, true);
    }

    if (this.activeCount >= this.concurrency && this.queue.length >= this.queueCapacity) {
      this.totals.saturated += 1;
      this.warnRateLimited("saturated", {
        event: "workspace_git_scan",
        operation: input.operation,
        workspaceHash,
        outcome: "saturated",
        activeCount: this.activeCount,
        queuedCount: this.queue.length,
        saturationCount: this.totals.saturated,
      }, "workspace Git scan queue saturated");
      throw new WorkspaceGitScanError(
        WORKSPACE_GIT_SCAN_ERROR_CODES.saturated,
        "Changed files are temporarily unavailable because the Git scan queue is full",
        {
          workspaceHash,
          activeCount: this.activeCount,
          queuedCount: this.queue.length,
          retryAfterSeconds: 1,
        },
      );
    }

    const fairnessKeys = Array.from(new Set([
      `repository:${workspaceHash}`,
      ...(input.fairnessKeys ?? []).filter(Boolean),
    ])).sort();
    const scan: PendingScan = {
      key,
      operation: input.operation,

View on GitHub (pinned to 120ae5428f)

Solutions

1. The Git scan queue is full. Retry shortly; if persistent, reduce scan request frequency or investigate slow scans.

When it happens

Trigger: Thrown at server/src/services/workspace-git-operation-scheduler.ts:536 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@120ae5428f (2026-08-18). Data as JSON: /api/errors/9860b6c882681afd. Report an issue: GitHub.