Stirling-Tools/Stirling-PDF · error · Error

Failed to load images for pages ${missing.map((i) => i + 1).

Error message

Failed to load images for pages ${missing.map((i) => i + 1).join(", ")}

What it means

Thrown in handleGeneratePdf's ensureImagesForPages helper when, after a 15-second polling window (maxWaitTime=15000ms, pollInterval=150ms), some requested page indices are still not present in loadedImagePagesRef. In lazy-image mode, page images are fetched on-demand from the server — this error means those fetches did not complete within the timeout. The message includes the 1-based page numbers that failed.

Source

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

            const allLoaded = uniqueIndices.every(
              (index) =>
                loadedImagePagesRef.current.has(index) &&
                imagesByPageRef.current[index] !== undefined,
            );
            const anyLoading = uniqueIndices.some((index) =>
              loadingImagePagesRef.current.has(index),
            );
            if (allLoaded && !anyLoading) {
              return;
            }
            await new Promise((resolve) => setTimeout(resolve, pollInterval));
          }

          const missing = uniqueIndices.filter(
            (index) => !loadedImagePagesRef.current.has(index),
          );
          if (missing.length > 0) {
            throw new Error(
              `Failed to load images for pages ${missing.map((i) => i + 1).join(", ")}`,
            );
          }
        };

        const currentDoc = loadedDocumentRef.current;
        const totalPages = currentDoc?.pages?.length ?? 0;
        const dirtyPageIndices = dirtyPages
          .map((isDirty, index) => (isDirty ? index : -1))
          .filter((index) => index >= 0);

        const canUseIncremental =
          isLazyMode && cachedJobId && dirtyPageIndices.length > 0;

        if (canUseIncremental) {
          await ensureImagesForPages(dirtyPageIndices);

          try {

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Increase maxWaitTime for documents with many pages or complex content.
2. Retry loading specific failed pages individually rather than failing the entire export.
3. Fall back to non-lazy mode (full document load) if image loading consistently fails.
4. Check the server's image generation endpoint for errors on the specific page indices.

Example fix

// before
const maxWaitTime = 15000;
const pollInterval = 150;

// after
const maxWaitTime = Math.max(15000, uniqueIndices.length * 3000);
const pollInterval = 150;

// Scale timeout based on page count
const maxWaitTime = Math.max(15000, uniqueIndices.length * 3000);
// Pre-load images for dirty pages proactively
for (const index of uniqueIndices) {
  if (!loadedImagePagesRef.current.has(index)) {
    loadImagesForPage(index); // fire without await for parallelism
  }
}

try {
  await ensureImagesForPages(dirtyPageIndices);
} catch (error) {
  if (error instanceof Error && error.message.startsWith('Failed to load images')) {
    // Retry failed pages once
    console.warn('Image load failed, retrying...', error.message);
    await new Promise(r => setTimeout(r, 1000));
    await ensureImagesForPages(dirtyPageIndices);
  } else {
    throw error;
  }
}

When it happens

Trigger: Server image generation for specific pages failed or is extremely slow. Network issues caused image fetch requests to time out. The server's lazy-image endpoint returned errors for those pages. Memory pressure caused image loading to be deferred or dropped.

Common situations: Large document with many pages where the server can't generate images fast enough. Specific pages with complex content (large images, vector graphics) taking longer to render. Server under concurrent load from multiple users.

Related errors

• policy run timed out
• Conversion timed out
• Incremental export failed for cached document. Please reload
• No pages to export
• Failed to export PDF: ${error instanceof Error ? error.messa

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