{"record":{"id":"16c156e7569c1a10","repo":"Stirling-Tools/Stirling-PDF","slug":"pdfium-failed-to-set-bitmap-on-image-object","errorCode":null,"errorMessage":"PDFium: failed to set bitmap on image object","messagePattern":"PDFium: failed to set bitmap on image object","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"frontend/editor/src/core/utils/imageToPdfUtils.ts","lineNumber":134,"sourceCode":"\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);\n      m.pdfium.setValue(matrixPtr, drawWidth, \"float\"); // a = scaleX\n      m.pdfium.setValue(matrixPtr + 4, 0, \"float\"); // b\n      m.pdfium.setValue(matrixPtr + 8, 0, \"float\"); // c\n      m.pdfium.setValue(matrixPtr + 12, drawHeight, \"float\"); // d = scaleY\n      m.pdfium.setValue(matrixPtr + 16, drawX, \"float\"); // e = translateX\n      m.pdfium.setValue(matrixPtr + 20, drawY, \"float\"); // f = translateY\n\n      const setMatrixOk = m.FPDFPageObj_SetMatrix(imageObjPtr, matrixPtr);\n      m.pdfium.wasmExports.free(matrixPtr);\n\n      if (!setMatrixOk) {\n        m.FPDFPageObj_Destroy(imageObjPtr);\n        throw new Error(\"PDFium: failed to set image matrix\");","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/Stirling-Tools/Stirling-PDF/blob/9ef20dcab80b85041912f045e17a6aea1d08f969/frontend/editor/src/core/utils/imageToPdfUtils.ts#L116-L152","documentation":"Thrown when FPDFImageObj_SetBitmap(pagePtr, 0, imageObjPtr, bitmapPtr) returns falsy, meaning PDFium refused to bind the bitmap to the image object. By this point the document, page, bitmap, and image object all exist. The bitmap is destroyed before throwing; the image object is also destroyed to avoid leaks. A failure here usually indicates an internal inconsistency (e.g. bitmap/image-object mismatch).","triggerScenarios":"All prior PDFium allocations succeeded but the set-bitmap call returns 0. Possible causes: the image object and bitmap have incompatible properties, the page count argument is wrong, or an internal PDFium error. This is rare relative to the allocation errors.","commonSituations":"A specific image dimension or pixel-layout combination triggers a PDFium edge case. Concurrent/torn state from an earlier partial operation. A PDFium build/version bug for the given image shape.","solutions":["Try a different image resolution or page format to change the bitmap/image dimensions and bypass the edge case.","Re-encode the source image (e.g. re-save as PNG/JPEG) to rule out a malformed input triggering the PDFium path.","Update the bundled PDFium WASM build in case the failure is a fixed bug.","Log imageWidth, imageHeight, and stride alongside the error to correlate with PDFium behavior."],"exampleFix":"// before\nconvertImageToPdf(file, { pageFormat: 'keep' }) // set-bitmap fails\n// after — change dimensions/page format to bypass the edge case\nconvertImageToPdf(file, { pageFormat: 'A4', imageResolution: 'reduced' })","handlingStrategy":"try-catch","validationCode":"// Indirect: change image dimensions/page format to bypass the edge case.\nif (imageWidth <= 0 || imageHeight <= 0) {\n  throw new Error('Invalid image dimensions for PDF conversion.');\n}","typeGuard":"function arePositiveDimensions(w: number, h: number): boolean {\n  return Number.isFinite(w) && Number.isFinite(h) && w > 0 && h > 0;\n}","tryCatchPattern":"try {\n  await convertImageToPdf(file, { pageFormat: 'A4', imageResolution: 'reduced' });\n} catch (e) {\n  const reason = (e as Error & { cause?: Error }).cause?.message ?? e.message;\n  if (reason.includes('failed to set bitmap')) {\n    showUser('Could not attach the image to the PDF. Try re-saving the image or using a different format.');\n  } else { throw e; }\n}","preventionTips":["Re-encode source images (re-save as PNG/JPEG) to rule out malformed input.","Try alternate page format/resolution to bypass PDFium edge cases.","Keep the PDFium WASM build up to date.","Log imageWidth, imageHeight, and stride with the error for correlation."],"tags":["image-to-pdf","pdfium","wasm","bitmap","binding"],"backgroundTag":null,"analyzedSha":"9ef20dcab80b85041912f045e17a6aea1d08f969","analyzedAt":"2026-08-13T22:11:39.827Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}