Stirling-Tools/Stirling-PDF · critical · Error

PDFium: failed to set bitmap on image object

Error message

PDFium: failed to set bitmap on image object

What it means

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).

Source

Thrown at frontend/editor/src/core/utils/imageToPdfUtils.ts:134

      // Create image page object
      const imageObjPtr = m.FPDFPageObj_NewImageObj(docPtr);
      if (!imageObjPtr) {
        m.FPDFBitmap_Destroy(bitmapPtr);
        throw new Error("PDFium: failed to create image object");
      }

      const setBitmapOk = m.FPDFImageObj_SetBitmap(
        pagePtr,
        0,
        imageObjPtr,
        bitmapPtr,
      );
      m.FPDFBitmap_Destroy(bitmapPtr);

      if (!setBitmapOk) {
        m.FPDFPageObj_Destroy(imageObjPtr);
        throw new Error("PDFium: failed to set bitmap on image object");
      }

      // Set transformation matrix: scale + translate
      // FS_MATRIX: {a, b, c, d, e, f} — 6 floats
      const matrixPtr = m.pdfium.wasmExports.malloc(6 * 4);
      m.pdfium.setValue(matrixPtr, drawWidth, "float"); // a = scaleX
      m.pdfium.setValue(matrixPtr + 4, 0, "float"); // b
      m.pdfium.setValue(matrixPtr + 8, 0, "float"); // c
      m.pdfium.setValue(matrixPtr + 12, drawHeight, "float"); // d = scaleY
      m.pdfium.setValue(matrixPtr + 16, drawX, "float"); // e = translateX
      m.pdfium.setValue(matrixPtr + 20, drawY, "float"); // f = translateY

      const setMatrixOk = m.FPDFPageObj_SetMatrix(imageObjPtr, matrixPtr);
      m.pdfium.wasmExports.free(matrixPtr);

      if (!setMatrixOk) {
        m.FPDFPageObj_Destroy(imageObjPtr);
        throw new Error("PDFium: failed to set image matrix");

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Try a different image resolution or page format to change the bitmap/image dimensions and bypass the edge case.
2. Re-encode the source image (e.g. re-save as PNG/JPEG) to rule out a malformed input triggering the PDFium path.
3. Update the bundled PDFium WASM build in case the failure is a fixed bug.
4. Log imageWidth, imageHeight, and stride alongside the error to correlate with PDFium behavior.

Example fix

// before
convertImageToPdf(file, { pageFormat: 'keep' }) // set-bitmap fails
// after — change dimensions/page format to bypass the edge case
convertImageToPdf(file, { pageFormat: 'A4', imageResolution: 'reduced' })

// Indirect: change image dimensions/page format to bypass the edge case.
if (imageWidth <= 0 || imageHeight <= 0) {
  throw new Error('Invalid image dimensions for PDF conversion.');
}

function arePositiveDimensions(w: number, h: number): boolean {
  return Number.isFinite(w) && Number.isFinite(h) && w > 0 && h > 0;
}

try {
  await convertImageToPdf(file, { pageFormat: 'A4', imageResolution: 'reduced' });
} catch (e) {
  const reason = (e as Error & { cause?: Error }).cause?.message ?? e.message;
  if (reason.includes('failed to set bitmap')) {
    showUser('Could not attach the image to the PDF. Try re-saving the image or using a different format.');
  } else { throw e; }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• PDFium: failed to create bitmap
• PDFium: failed to create document
• PDFium: failed to create page
• PDFium: failed to create image object
• PDFium: failed to set image matrix

AI-assisted analysis of Stirling-Tools/Stirling-PDF@9ef20dcab8 (2026-08-13). Data as JSON: /api/errors/16c156e7569c1a10. Report an issue: GitHub.