Stirling-Tools/Stirling-PDF · critical · Error

PDFium: failed to create page

Error message

PDFium: failed to create page

What it means

Thrown when FPDFPage_New(docPtr, 0, pageWidth, pageHeight) returns null after the document was successfully created. The page (with the computed width/height in PDF points) could not be allocated inside the document. Failure at this stage typically indicates resource exhaustion or invalid page dimensions.

Source

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

        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);
      if (!imageObjPtr) {
        m.FPDFBitmap_Destroy(bitmapPtr);
        throw new Error("PDFium: failed to create image object");
      }

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Validate imageWidth/imageHeight are finite positive numbers before computing page dimensions.
2. Use a fixed page format (A4/letter) instead of 'keep' for very large images to bound page size.
3. Reduce image resolution to lower overall memory pressure.
4. Catch and surface a user-friendly 'could not build page' error with the image dimensions logged.

Example fix

// before
// pageFormat 'keep' on a 50000x50000 image -> huge page -> null
convertImageToPdf(file, { pageFormat: 'keep' })
// after
convertImageToPdf(file, { pageFormat: 'A4', imageResolution: 'reduced' })

function areValidPageDimensions(w: number, h: number): boolean {
  return Number.isFinite(w) && Number.isFinite(h) && w > 0 && h > 0 && w < 14400 && h < 14400;
}
// Validate imageWidth/imageHeight from decodeImageToRgba before computing page size.

function areFiniteDimensions(w: unknown, h: unknown): w is number {
  return typeof w === 'number' && typeof h === 'number' &&
    Number.isFinite(w) && Number.isFinite(h) && w > 0 && h > 0;
}

try {
  await convertImageToPdf(file, { pageFormat: 'A4' });
} catch (e) {
  const reason = (e as Error & { cause?: Error }).cause?.message ?? e.message;
  if (reason.includes('failed to create page')) {
    showUser('Could not create a PDF page for this image. Try a smaller resolution or A4 format.');
  } else { throw e; }
}

When it happens

Trigger: The document pointer is valid but FPDFPage_New returns 0. Possible causes: WASM memory exhausted after document creation; pageWidth/pageHeight are non-finite, negative, or absurdly large values that PDFium rejects. Reached only after FPDF_CreateNewDocument succeeded.

Common situations: Very large image producing extreme page dimensions (pageFormat 'keep' on a huge image). NaN/Infinity in pageWidth/pageHeight from a division by zero (e.g. zero-aspect or corrupt image metrics). Memory pressure after allocating the document.

Related errors

• PDFium: failed to create document
• 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/f6930abdbf57aa06. Report an issue: GitHub.