{"record":{"id":"787ccca486d28085","repo":"Stirling-Tools/Stirling-PDF","slug":"pdfium-failed-to-create-document-787ccc","errorCode":null,"errorMessage":"PDFium: failed to create document","messagePattern":"PDFium: failed to create document","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"frontend/editor/src/core/utils/imageToPdfUtils.ts","lineNumber":100,"sourceCode":"      const imageAspectRatio = imageWidth / imageHeight;\n      const pageAspectRatio = pageWidth / pageHeight;\n\n      if (imageAspectRatio > pageAspectRatio) {\n        drawWidth = pageWidth;\n        drawHeight = pageWidth / imageAspectRatio;\n        drawX = 0;\n        drawY = (pageHeight - drawHeight) / 2;\n      } else {\n        drawHeight = pageHeight;\n        drawWidth = pageHeight * imageAspectRatio;\n        drawY = 0;\n        drawX = (pageWidth - drawWidth) / 2;\n      }\n    }\n\n    // Create new PDF document\n    const docPtr = m.FPDF_CreateNewDocument();\n    if (!docPtr) throw new Error(\"PDFium: failed to create document\");\n\n    try {\n      // Create a page\n      const pagePtr = m.FPDFPage_New(docPtr, 0, pageWidth, pageHeight);\n      if (!pagePtr) throw new Error(\"PDFium: failed to create page\");\n\n      // Create bitmap from RGBA data (PDFium uses BGRA)\n      const bitmapPtr = m.FPDFBitmap_Create(imageWidth, imageHeight, 1);\n      if (!bitmapPtr) throw new Error(\"PDFium: failed to create bitmap\");\n\n      const bufferPtr = m.FPDFBitmap_GetBuffer(bitmapPtr);\n      const stride = m.FPDFBitmap_GetStride(bitmapPtr);\n\n      // Bulk RGBA → BGRA copy via shared utility\n      copyRgbaToBgraHeap(m, rgba, bufferPtr, imageWidth, imageHeight, stride);\n\n      // Create image page object\n      const imageObjPtr = m.FPDFPageObj_NewImageObj(docPtr);","sourceCodeStart":82,"sourceCodeEnd":118,"githubUrl":"https://github.com/Stirling-Tools/Stirling-PDF/blob/9ef20dcab80b85041912f045e17a6aea1d08f969/frontend/editor/src/core/utils/imageToPdfUtils.ts#L82-L118","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Reduce image resolution before conversion (pass imageResolution: 'reduced' to cap at 1200px).","Ensure prior PDFium documents are closed (FPDF_CloseDocument in finally) so memory is reclaimed between conversions.","Process very large images in smaller batches or server-side instead of in-browser WASM.","Catch the error and inform the user the image is too large for in-browser conversion."],"exampleFix":"// before\nconvertImageToPdf(hugeFile, { imageResolution: 'full' }) // OOM at doc creation\n// after\nconvertImageToPdf(hugeFile, { imageResolution: 'reduced' })","handlingStrategy":"validation","validationCode":"const MAX_PIXELS = 25_000_000; // ~25MP safety ceiling\nfunction isWithinMemoryBudget(width: number, height: number): boolean {\n  return Number.isFinite(width) && Number.isFinite(height) &&\n    width > 0 && height > 0 && width * height <= MAX_PIXELS;\n}\n// Pre-decode the image to get dimensions, validate, then call convertImageToPdf with 'reduced' if over budget.","typeGuard":"function isSafeImageSize(width: number, height: number): boolean {\n  return width > 0 && height > 0 && width * height <= MAX_PIXELS;\n}","tryCatchPattern":"try {\n  await convertImageToPdf(file, { imageResolution: 'reduced' });\n} catch (e) {\n  const reason = (e as Error & { cause?: Error }).cause?.message ?? e.message;\n  if (reason.includes('failed to create document')) {\n    showUser('The image is too large for in-browser conversion. Try reducing its resolution.');\n  } else { throw e; }\n}","preventionTips":["Default to imageResolution: 'reduced' for large images.","Cap input pixel dimensions before conversion.","Ensure prior PDFium documents are closed between conversions.","Route very large images to a server-side conversion endpoint."],"tags":["image-to-pdf","pdfium","wasm","memory","allocation"],"backgroundTag":null,"analyzedSha":"9ef20dcab80b85041912f045e17a6aea1d08f969","analyzedAt":"2026-08-13T22:11:39.827Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}