{"record":{"id":"be0a054280853a3b","repo":"Stirling-Tools/Stirling-PDF","slug":"pdfium-failed-to-create-bitmap","errorCode":null,"errorMessage":"PDFium: failed to create bitmap","messagePattern":"PDFium: failed to create bitmap","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"frontend/editor/src/core/utils/imageToPdfUtils.ts","lineNumber":109,"sourceCode":"        drawHeight = pageHeight;\n        drawWidth = pageHeight * imageAspectRatio;\n        drawY = 0;\n        drawX = (pageWidth - drawWidth) / 2;\n      }\n    }\n\n    // Create new PDF document\n    const docPtr = m.FPDF_CreateNewDocument();\n    if (!docPtr) throw new Error(\"PDFium: failed to create document\");\n\n    try {\n      // Create a page\n      const pagePtr = m.FPDFPage_New(docPtr, 0, pageWidth, pageHeight);\n      if (!pagePtr) throw new Error(\"PDFium: failed to create page\");\n\n      // Create bitmap from RGBA data (PDFium uses BGRA)\n      const bitmapPtr = m.FPDFBitmap_Create(imageWidth, imageHeight, 1);\n      if (!bitmapPtr) throw new Error(\"PDFium: failed to create bitmap\");\n\n      const bufferPtr = m.FPDFBitmap_GetBuffer(bitmapPtr);\n      const stride = m.FPDFBitmap_GetStride(bitmapPtr);\n\n      // Bulk RGBA → BGRA copy via shared utility\n      copyRgbaToBgraHeap(m, rgba, bufferPtr, imageWidth, imageHeight, stride);\n\n      // Create image page object\n      const imageObjPtr = m.FPDFPageObj_NewImageObj(docPtr);\n      if (!imageObjPtr) {\n        m.FPDFBitmap_Destroy(bitmapPtr);\n        throw new Error(\"PDFium: failed to create image object\");\n      }\n\n      const setBitmapOk = m.FPDFImageObj_SetBitmap(\n        pagePtr,\n        0,\n        imageObjPtr,","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/Stirling-Tools/Stirling-PDF/blob/9ef20dcab80b85041912f045e17a6aea1d08f969/frontend/editor/src/core/utils/imageToPdfUtils.ts#L91-L127","documentation":"Thrown when FPDFBitmap_Create(imageWidth, imageHeight, 1) returns null — PDFium could not allocate the bitmap buffer that holds the image's RGBA/BGRA pixels. The buffer size is width*height*4 bytes, so a large image demands a very large contiguous allocation; failure means the WASM heap could not satisfy it.","triggerScenarios":"The image dimensions are large enough that width*height*4 bytes exceeds available WASM heap. Reached after document and page creation succeeded, so memory was already partially consumed. The third argument (1) requests an alpha channel, marginally increasing size.","commonSituations":"High-megapixel photo (e.g. 8000x6000 -> ~192MB just for the bitmap). Multiple conversions accumulating. A device/tab with a low WASM memory ceiling. The 'reduced' resolution option was not used.","solutions":["Pass imageResolution: 'reduced' to cap the longest side at 1200px before bitmap creation.","Reject or downscale images above a pixel-count threshold before calling convertImageToPdf.","Ensure no other large PDFium allocations are live concurrently.","Surface a clear 'image too large for in-browser conversion' error to the user."],"exampleFix":"// before\nconvertImageToPdf(bigPhoto, { imageResolution: 'full' }) // bitmap alloc fails\n// after\nconvertImageToPdf(bigPhoto, { imageResolution: 'reduced' })","handlingStrategy":"validation","validationCode":"const MAX_BITMAP_BYTES = 200 * 1024 * 1024; // 200MB ceiling\nfunction bitmapFitsBudget(width: number, height: number): boolean {\n  return width * height * 4 <= MAX_BITMAP_BYTES;\n}\nif (!bitmapFitsBudget(imageWidth, imageHeight)) {\n  throw new Error('Image too large for in-browser bitmap. Reduce resolution.');\n}","typeGuard":"function isBitmapAllocatable(width: number, height: number): boolean {\n  return Number.isFinite(width) && Number.isFinite(height) &&\n    width > 0 && height > 0 && width * height * 4 <= MAX_BITMAP_BYTES;\n}","tryCatchPattern":"try {\n  await convertImageToPdf(file, { imageResolution: 'reduced' });\n} catch (e) {\n  const reason = (e as Error & { cause?: Error }).cause?.message ?? e.message;\n  if (reason.includes('failed to create bitmap')) {\n    showUser('The image is too large to process in-browser. Use a smaller image or server-side conversion.');\n  } else { throw e; }\n}","preventionTips":["Use imageResolution: 'reduced' (1200px cap) for large images.","Reject images above a pixel-count threshold before conversion.","Close prior PDFium documents to free heap between conversions.","Offer server-side conversion as a fallback for very large images."],"tags":["image-to-pdf","pdfium","wasm","memory","bitmap"],"backgroundTag":null,"analyzedSha":"9ef20dcab80b85041912f045e17a6aea1d08f969","analyzedAt":"2026-08-13T22:11:39.827Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}