{"record":{"id":"87fc4b12f3ce7c9f","repo":"Stirling-Tools/Stirling-PDF","slug":"pdfium-failed-to-create-image-object","errorCode":null,"errorMessage":"PDFium: failed to create image object","messagePattern":"PDFium: failed to create image object","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"frontend/editor/src/core/utils/imageToPdfUtils.ts","lineNumber":121,"sourceCode":"      // 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,\n        bitmapPtr,\n      );\n      m.FPDFBitmap_Destroy(bitmapPtr);\n\n      if (!setBitmapOk) {\n        m.FPDFPageObj_Destroy(imageObjPtr);\n        throw new Error(\"PDFium: failed to set bitmap on image object\");\n      }\n\n      // Set transformation matrix: scale + translate\n      // FS_MATRIX: {a, b, c, d, e, f} — 6 floats\n      const matrixPtr = m.pdfium.wasmExports.malloc(6 * 4);","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/Stirling-Tools/Stirling-PDF/blob/9ef20dcab80b85041912f045e17a6aea1d08f969/frontend/editor/src/core/utils/imageToPdfUtils.ts#L103-L139","documentation":"Thrown when FPDFPageObj_NewImageObj(docPtr) returns null after the bitmap was created. This allocates a PDF image object (the XObject that will reference the bitmap); a null pointer means PDFium could not create the object, typically due to memory pressure. The bitmap is correctly destroyed before throwing to avoid a leak.","triggerScenarios":"Document, page, and bitmap were all created successfully, but the image-object allocation fails. Memory exhaustion is the primary cause. Reached only on the image-object creation path; the cleanup (FPDFBitmap_Destroy) runs first.","commonSituations":"Cumulative memory usage from a large bitmap plus document/page leaves no room for the image object. Repeated conversions in a memory-constrained tab. The image is large enough that each PDFium object pushes the heap past its limit.","solutions":["Reduce image resolution to lower the bitmap size and overall footprint.","Ensure prior PDFium documents are closed between conversions to free the heap.","Downscale very large images before passing them in.","Catch and inform the user; suggest server-side conversion for very large images."],"exampleFix":"// before\nconvertImageToPdf(largeImg) // image object alloc fails after bitmap\n// after\nconvertImageToPdf(largeImg, { imageResolution: 'reduced' })","handlingStrategy":"validation","validationCode":"// No direct pre-check; rely on bounding memory. Ensure prior docs are closed.\nconst MAX_PIXELS = 25_000_000;\nif (imageWidth * imageHeight > MAX_PIXELS) {\n  throw new Error('Image too large; reduce resolution before conversion.');\n}","typeGuard":"function isWithinPixelBudget(w: number, h: number): boolean {\n  return w * h <= MAX_PIXELS;\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 image object')) {\n    showUser('Not enough memory to build the image object. Try a smaller image.');\n  } else { throw e; }\n}","preventionTips":["Reduce image resolution before conversion.","Close prior PDFium documents between conversions to free memory.","Bound input image pixel counts.","Route oversized images to server-side conversion."],"tags":["image-to-pdf","pdfium","wasm","memory","image-object"],"backgroundTag":null,"analyzedSha":"9ef20dcab80b85041912f045e17a6aea1d08f969","analyzedAt":"2026-08-13T22:11:39.827Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}