{"record":{"id":"3624417fb6550cdc","repo":"Stirling-Tools/Stirling-PDF","slug":"failed-to-load-images-for-pages-missing-map-i","errorCode":null,"errorMessage":"Failed to load images for pages ${missing.map((i) => i + 1).join(\", \")}","messagePattern":"Failed to load images for pages (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"frontend/editor/src/core/tools/pdfTextEditor/PdfTextEditor.tsx","lineNumber":1293,"sourceCode":"            const allLoaded = uniqueIndices.every(\n              (index) =>\n                loadedImagePagesRef.current.has(index) &&\n                imagesByPageRef.current[index] !== undefined,\n            );\n            const anyLoading = uniqueIndices.some((index) =>\n              loadingImagePagesRef.current.has(index),\n            );\n            if (allLoaded && !anyLoading) {\n              return;\n            }\n            await new Promise((resolve) => setTimeout(resolve, pollInterval));\n          }\n\n          const missing = uniqueIndices.filter(\n            (index) => !loadedImagePagesRef.current.has(index),\n          );\n          if (missing.length > 0) {\n            throw new Error(\n              `Failed to load images for pages ${missing.map((i) => i + 1).join(\", \")}`,\n            );\n          }\n        };\n\n        const currentDoc = loadedDocumentRef.current;\n        const totalPages = currentDoc?.pages?.length ?? 0;\n        const dirtyPageIndices = dirtyPages\n          .map((isDirty, index) => (isDirty ? index : -1))\n          .filter((index) => index >= 0);\n\n        const canUseIncremental =\n          isLazyMode && cachedJobId && dirtyPageIndices.length > 0;\n\n        if (canUseIncremental) {\n          await ensureImagesForPages(dirtyPageIndices);\n\n          try {","sourceCodeStart":1275,"sourceCodeEnd":1311,"githubUrl":"https://github.com/Stirling-Tools/Stirling-PDF/blob/9ef20dcab80b85041912f045e17a6aea1d08f969/frontend/editor/src/core/tools/pdfTextEditor/PdfTextEditor.tsx#L1275-L1311","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Increase maxWaitTime for documents with many pages or complex content.","Retry loading specific failed pages individually rather than failing the entire export.","Fall back to non-lazy mode (full document load) if image loading consistently fails.","Check the server's image generation endpoint for errors on the specific page indices."],"exampleFix":"// before\nconst maxWaitTime = 15000;\nconst pollInterval = 150;\n\n// after\nconst maxWaitTime = Math.max(15000, uniqueIndices.length * 3000);\nconst pollInterval = 150;","handlingStrategy":"retry","validationCode":"// Scale timeout based on page count\nconst maxWaitTime = Math.max(15000, uniqueIndices.length * 3000);\n// Pre-load images for dirty pages proactively\nfor (const index of uniqueIndices) {\n  if (!loadedImagePagesRef.current.has(index)) {\n    loadImagesForPage(index); // fire without await for parallelism\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await ensureImagesForPages(dirtyPageIndices);\n} catch (error) {\n  if (error instanceof Error && error.message.startsWith('Failed to load images')) {\n    // Retry failed pages once\n    console.warn('Image load failed, retrying...', error.message);\n    await new Promise(r => setTimeout(r, 1000));\n    await ensureImagesForPages(dirtyPageIndices);\n  } else {\n    throw error;\n  }\n}","preventionTips":["Scale maxWaitTime based on the number of pages being loaded.","Preload page images when the user starts editing, not just at export time.","Retry individual failed page loads before failing the entire export.","Fall back to full (non-incremental) export if lazy image loading is unreliable."],"tags":["pdf-text-editor","lazy-loading","images","timeout","export"],"backgroundTag":null,"analyzedSha":"9ef20dcab80b85041912f045e17a6aea1d08f969","analyzedAt":"2026-08-13T22:11:39.827Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}