Stirling-Tools/Stirling-PDF · critical · Error

PDFium: failed to create bitmap

Error message

PDFium: failed to create bitmap

What it means

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.

Source

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

        drawHeight = pageHeight;
        drawWidth = pageHeight * imageAspectRatio;
        drawY = 0;
        drawX = (pageWidth - drawWidth) / 2;
      }
    }

    // Create new PDF document
    const docPtr = m.FPDF_CreateNewDocument();
    if (!docPtr) throw new Error("PDFium: failed to create document");

    try {
      // 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,

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Pass imageResolution: 'reduced' to cap the longest side at 1200px before bitmap creation.
2. Reject or downscale images above a pixel-count threshold before calling convertImageToPdf.
3. Ensure no other large PDFium allocations are live concurrently.
4. Surface a clear 'image too large for in-browser conversion' error to the user.

Example fix

// before
convertImageToPdf(bigPhoto, { imageResolution: 'full' }) // bitmap alloc fails
// after
convertImageToPdf(bigPhoto, { imageResolution: 'reduced' })

const MAX_BITMAP_BYTES = 200 * 1024 * 1024; // 200MB ceiling
function bitmapFitsBudget(width: number, height: number): boolean {
  return width * height * 4 <= MAX_BITMAP_BYTES;
}
if (!bitmapFitsBudget(imageWidth, imageHeight)) {
  throw new Error('Image too large for in-browser bitmap. Reduce resolution.');
}

function isBitmapAllocatable(width: number, height: number): boolean {
  return Number.isFinite(width) && Number.isFinite(height) &&
    width > 0 && height > 0 && width * height * 4 <= MAX_BITMAP_BYTES;
}

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 bitmap')) {
    showUser('The image is too large to process in-browser. Use a smaller image or server-side conversion.');
  } else { throw e; }
}

When it happens

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

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

Related errors

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

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