Stirling-Tools/Stirling-PDF · critical · Error

PDFium: failed to create image object

Error message

PDFium: failed to create image object

What it means

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.

Source

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

      // Create a page
      const pagePtr = m.FPDFPage_New(docPtr, 0, pageWidth, pageHeight);
      if (!pagePtr) throw new Error("PDFium: failed to create page");

      // Create bitmap from RGBA data (PDFium uses BGRA)
      const bitmapPtr = m.FPDFBitmap_Create(imageWidth, imageHeight, 1);
      if (!bitmapPtr) throw new Error("PDFium: failed to create bitmap");

      const bufferPtr = m.FPDFBitmap_GetBuffer(bitmapPtr);
      const stride = m.FPDFBitmap_GetStride(bitmapPtr);

      // Bulk RGBA → BGRA copy via shared utility
      copyRgbaToBgraHeap(m, rgba, bufferPtr, imageWidth, imageHeight, stride);

      // 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);

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Reduce image resolution to lower the bitmap size and overall footprint.
2. Ensure prior PDFium documents are closed between conversions to free the heap.
3. Downscale very large images before passing them in.
4. Catch and inform the user; suggest server-side conversion for very large images.

Example fix

// before
convertImageToPdf(largeImg) // image object alloc fails after bitmap
// after
convertImageToPdf(largeImg, { imageResolution: 'reduced' })

// No direct pre-check; rely on bounding memory. Ensure prior docs are closed.
const MAX_PIXELS = 25_000_000;
if (imageWidth * imageHeight > MAX_PIXELS) {
  throw new Error('Image too large; reduce resolution before conversion.');
}

function isWithinPixelBudget(w: number, h: number): boolean {
  return w * h <= MAX_PIXELS;
}

try {
  await convertImageToPdf(file, { imageResolution: 'reduced' });
} catch (e) {
  const reason = (e as Error & { cause?: Error }).cause?.message ?? e.message;
  if (reason.includes('failed to create image object')) {
    showUser('Not enough memory to build the image object. Try a smaller image.');
  } else { throw e; }
}

When it happens

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

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

Related errors

• PDFium: failed to create document
• PDFium: failed to create page
• PDFium: failed to create bitmap
• PDFium: failed to create document
• PDFium: failed to create destination document

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