{"record":{"id":"b5612e10674ec90a","repo":"Stirling-Tools/Stirling-PDF","slug":"pdfium-failed-to-render-page-0","errorCode":null,"errorMessage":"PDFium: failed to render page 0","messagePattern":"PDFium: failed to render page 0","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"frontend/editor/src/core/utils/thumbnailUtils.ts","lineNumber":124,"sourceCode":"      new RegExp(`error ${PDFIUM_ERR_PASSWORD}`).test(error.message)\n    ) {\n      return {\n        thumbnail: \"\",\n        pageCount: 1,\n        pageRotations: [],\n        pageDimensions: [],\n        isEncrypted: true,\n      };\n    }\n    throw error;\n  }\n\n  try {\n    const pageCount = m.FPDF_GetPageCount(docPtr);\n    const thumbnail = await renderPdfiumPageDataUrl(docPtr, 0, scale, {\n      applyRotation,\n    });\n    if (!thumbnail) throw new Error(\"PDFium: failed to render page 0\");\n\n    // Page 0 metadata is already available via the render, but read it\n    // directly for consistency with the later per-page loop.\n    const firstMeta = await readPdfiumPageMetadata(docPtr, 0);\n    const pageRotations: number[] = [firstMeta?.rotation ?? 0];\n    const pageDimensions: Array<{ width: number; height: number }> = [\n      {\n        width: firstMeta?.width ?? 0,\n        height: firstMeta?.height ?? 0,\n      },\n    ];\n\n    if (collectAllPagesMetadata) {\n      for (let i = 1; i < pageCount; i++) {\n        const meta = await readPdfiumPageMetadata(docPtr, i);\n        if (!meta) continue;\n        pageRotations[i] = meta.rotation;\n        pageDimensions[i] = { width: meta.width, height: meta.height };","sourceCodeStart":106,"sourceCodeEnd":142,"githubUrl":"https://github.com/Stirling-Tools/Stirling-PDF/blob/9ef20dcab80b85041912f045e17a6aea1d08f969/frontend/editor/src/core/utils/thumbnailUtils.ts#L106-L142","documentation":"Thrown in generatePdfiumThumbnail (single-thumbnail variant) when renderPdfiumPageDataUrl(docPtr, 0, scale, {applyRotation}) returned null/falsy. The document opened successfully (password errors are caught earlier), so a null render means PDFium could not rasterize page 0 — corrupt page content, unsupported PDF features crashing the WASM render, zero-size page geometry, or scale producing a 0x0 bitmap.","triggerScenarios":"A PDF whose page 0 has no/zero dimensions; scale resolved to 0 from a degenerate thumbnail-size config; a PDF using features the bundled PDFium build cannot render; WASM memory exhaustion during rasterization.","commonSituations":"Thumbnail generation at import time for an unusual/corrupt PDF; very low thumbnail target size; PDFs from generators PDFium partially supports.","solutions":["Clamp scale to a minimum positive value before rendering.","Validate page dimensions (readPdfiumPageMetadata) are positive before rendering; if not, return an empty-thumbnail placeholder.","On null render, fall back to a placeholder thumbnail and continue loading rather than failing the whole import.","Ensure the WASM module heap is large enough for the rasterized bitmap."],"exampleFix":"// before\nconst thumbnail = await renderPdfiumPageDataUrl(docPtr, 0, scale, { applyRotation });\nif (!thumbnail) throw new Error(\"PDFium: failed to render page 0\");\n\n// after\nconst thumbnail = await renderPdfiumPageDataUrl(docPtr, 0, scale, { applyRotation });\nif (!thumbnail) {\n  // Return a placeholder so import continues; surface a non-fatal warning instead of aborting.\n  return { thumbnail: \"\", pageCount, pageRotations: [], pageDimensions: [], isEncrypted: false, renderFailed: true };\n}","handlingStrategy":"fallback","validationCode":"const meta = await readPdfiumPageMetadata(docPtr, 0);\nif (!meta || meta.width <= 0 || meta.height <= 0) {\n  // skip render, return placeholder\n}\nconst safeScale = scale > 0 ? scale : 0.2;","typeGuard":"const hasValidPageGeometry = (m: { width: number; height: number } | null): m is { width: number; height: number } =>\n  !!m && m.width > 0 && m.height > 0;","tryCatchPattern":"try {\n  const thumb = await generatePdfiumThumbnail(data, scale);\n} catch (error) {\n  if (/failed to render page 0/.test((error as Error).message)) {\n    return { thumbnail: \"\", pageCount: 1, pageRotations: [], pageDimensions: [], renderFailed: true };\n  }\n  throw error;\n}","preventionTips":["Clamp scale to a minimum positive value before rendering.","Validate page dimensions are positive before rendering.","Degrade to a placeholder thumbnail on render failure instead of aborting import."],"tags":["pdfium","wasm","thumbnail","rendering","fallback"],"backgroundTag":null,"analyzedSha":"9ef20dcab80b85041912f045e17a6aea1d08f969","analyzedAt":"2026-08-13T22:11:39.827Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}