Stirling-Tools/Stirling-PDF · error · Error

Incremental export failed for cached document. Please reload

Error message

Incremental export failed for cached document. Please reload and retry.

What it means

Thrown in handleGeneratePdf when the incremental export (partial/{cachedJobId} endpoint) fails and the code is in lazy mode with a cached jobId. Unlike non-lazy mode (which falls back to full export), lazy mode throws because the full export would require loading all page images first, which is expensive. The original error is attached as cause.

Source

Thrown at frontend/editor/src/core/tools/pdfTextEditor/PdfTextEditor.tsx:1359

            const contentDisposition =
              response.headers?.["content-disposition"] ?? "";
            const detectedName = getFilenameFromHeaders(contentDisposition);
            const downloadName = detectedName || expectedName;

            downloadBlob(response.data, downloadName);

            if (onComplete && !skipComplete) {
              const pdfFile = new File([response.data], downloadName, {
                type: "application/pdf",
              });
              onComplete([pdfFile]);
            }
            setErrorMessage(null);
            return;
          } catch (incrementalError) {
            if (isLazyMode && cachedJobIdRef.current) {
              throw new Error(
                "Incremental export failed for cached document. Please reload and retry.",
                {
                  cause: incrementalError,
                },
              );
            }
            console.warn(
              "[handleGeneratePdf] Incremental export failed, falling back to full export",
              incrementalError,
            );
          }
        }

        if (isLazyMode && totalPages > 0) {
          const allPageIndices = Array.from(
            { length: totalPages },
            (_, index) => index,
          );

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Clear the cached jobId (cachedJobIdRef.current = null) and reload the document to get a fresh conversion.
2. Fall back to full export despite the cost — load all page images and send the complete document.
3. Catch this specific error in the UI and show a 'Document cache expired, reloading...' message with automatic reload.
4. Refresh the cached job periodically if the document is open for a long time.

Example fix

// before
} catch (incrementalError) {
  if (isLazyMode && cachedJobIdRef.current) {
    throw new Error("Incremental export failed for cached document. Please reload and retry.", {
      cause: incrementalError,
    });
  }
  // fall back to full export
}

// after
} catch (incrementalError) {
  if (isLazyMode && cachedJobIdRef.current) {
    console.warn("Incremental export failed, falling back to full export", incrementalError);
    cachedJobIdRef.current = null;
    // Fall through to full export below
  }
}

// Check cached job validity before attempting incremental export
if (isLazyMode && cachedJobIdRef.current) {
  // Verify the job still exists
  try {
    await apiClient.get(`/api/v1/general/job/${cachedJobIdRef.current}`);
  } catch {
    // Job expired — clear cache and use full export
    cachedJobIdRef.current = null;
  }
}

} catch (incrementalError) {
  if (isLazyMode && cachedJobIdRef.current) {
    // Instead of throwing, fall back to full export
    console.warn('[handleGeneratePdf] Incremental export failed, falling back to full export', incrementalError);
    cachedJobIdRef.current = null;
    // Fall through to full export code below
  }
}

When it happens

Trigger: The cached jobId expired on the server (job retention TTL exceeded). The server restarted and lost the cached document state. The partial export endpoint returned an error (corrupt cache state, server bug). The document changed so significantly that the incremental patch is invalid.

Common situations: User edited a document, left it idle for a long time, then tried to export — the cached job expired. Server redeployed between conversion and export. Network instability during the partial export request.

Related errors

• Failed to load images for pages ${missing.map((i) => i + 1).
• No pages to export
• Failed to export PDF: ${error instanceof Error ? error.messa
• PDFium: failed to create destination document
• policy produced no output

AI-assisted analysis of Stirling-Tools/Stirling-PDF@9ef20dcab8 (2026-08-13). Data as JSON: /api/errors/37f61f538ecc0d98. Report an issue: GitHub.