Stirling-Tools/Stirling-PDF · critical · Error

PDFium: failed to create document

Error message

PDFium: failed to create document

What it means

Thrown when FPDF_CreateNewDocument() returns a null pointer, meaning PDFium WASM could not allocate a new empty PDF document. This is the first PDFium allocation in the pipeline; if it fails, no subsequent page/bitmap creation can proceed. A null here almost always indicates an exhausted-memory or failed-module-init condition rather than an input problem.

Source

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

      const imageAspectRatio = imageWidth / imageHeight;
      const pageAspectRatio = pageWidth / pageHeight;

      if (imageAspectRatio > pageAspectRatio) {
        drawWidth = pageWidth;
        drawHeight = pageWidth / imageAspectRatio;
        drawX = 0;
        drawY = (pageHeight - drawHeight) / 2;
      } else {
        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);

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Reduce image resolution before conversion (pass imageResolution: 'reduced' to cap at 1200px).
2. Ensure prior PDFium documents are closed (FPDF_CloseDocument in finally) so memory is reclaimed between conversions.
3. Process very large images in smaller batches or server-side instead of in-browser WASM.
4. Catch the error and inform the user the image is too large for in-browser conversion.

Example fix

// before
convertImageToPdf(hugeFile, { imageResolution: 'full' }) // OOM at doc creation
// after
convertImageToPdf(hugeFile, { imageResolution: 'reduced' })

const MAX_PIXELS = 25_000_000; // ~25MP safety ceiling
function isWithinMemoryBudget(width: number, height: number): boolean {
  return Number.isFinite(width) && Number.isFinite(height) &&
    width > 0 && height > 0 && width * height <= MAX_PIXELS;
}
// Pre-decode the image to get dimensions, validate, then call convertImageToPdf with 'reduced' if over budget.

function isSafeImageSize(width: number, height: number): boolean {
  return width > 0 && height > 0 && width * height <= 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 document')) {
    showUser('The image is too large for in-browser conversion. Try reducing its resolution.');
  } else { throw e; }
}

When it happens

Trigger: Calling convertImageToPdf when the PDFium WASM module is out of memory (the image is extremely large, or many documents are open), or when the WASM heap cannot grow. FPDF_CreateNewDocument allocates internal PDF structures; failure means the allocator returned 0.

Common situations: Processing a very high-resolution image (huge RGBA buffer already allocated by decodeImageToRgba) that leaves no room for the document. Repeated conversions without releasing prior PDFium documents. A constrained environment (low memory device, memory-limited browser tab).

Related errors

• PDFium: failed to create page
• PDFium: failed to create bitmap
• PDFium: failed to create image object
• 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/787ccca486d28085. Report an issue: GitHub.