{"record":{"id":"08e1f11827295bf6","repo":"Stirling-Tools/Stirling-PDF","slug":"pdfium-failed-to-create-document-08e1f1","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/services/pdfiumDocBuilder.ts","lineNumber":350,"sourceCode":"// Document abstraction\n// ---------------------------------------------------------------------------\n\nexport class PdfiumDocument {\n  readonly _m: WrappedPdfiumModule;\n  readonly _docPtr: number;\n  private _pages: PdfiumPage[] = [];\n  private _fonts: Map<string, PdfiumFont> = new Map();\n\n  private constructor(m: WrappedPdfiumModule, docPtr: number) {\n    this._m = m;\n    this._docPtr = docPtr;\n  }\n\n  /** Create a new empty PDF document. Drop-in replacement for `PDFDocument.create()`. */\n  static async create(): Promise<PdfiumDocument> {\n    const m = await getPdfiumModule();\n    const docPtr = m.FPDF_CreateNewDocument();\n    if (!docPtr) throw new Error(\"PDFium: failed to create document\");\n    return new PdfiumDocument(m, docPtr);\n  }\n\n  /** Add a new page to the document. */\n  addPage(dimensions: [number, number]): PdfiumPage {\n    const [width, height] = dimensions;\n    const insertIdx = this._pages.length;\n    const pagePtr = this._m.FPDFPage_New(\n      this._docPtr,\n      insertIdx,\n      width,\n      height,\n    );\n    if (!pagePtr) throw new Error(\"PDFium: failed to create page\");\n    const page = new PdfiumPage(this._m, this._docPtr, pagePtr, width, height);\n    this._pages.push(page);\n    return page;\n  }","sourceCodeStart":332,"sourceCodeEnd":368,"githubUrl":"https://github.com/Stirling-Tools/Stirling-PDF/blob/9ef20dcab80b85041912f045e17a6aea1d08f969/frontend/editor/src/core/services/pdfiumDocBuilder.ts#L332-L368","documentation":"`PdfiumDocument.create()` (the drop-in replacement for pdf-lib's `PDFDocument.create()`) calls `FPDF_CreateNewDocument()` and throws on a null pointer. An empty document failing to allocate points to WASM heap exhaustion or a corrupted/uninitialised module — `create()` is called early in builder flows, so if this fails, every subsequent builder operation would too.","triggerScenarios":"Calling `PdfiumDocument.create()` after heavy prior PDFium use filled the WASM heap; the module's `PDFiumExt_Init` failed during `initPdfiumModule` (caught and swallowed, leaving extensions unset); a prior unhandled pointer error left PDFium in a bad state.","commonSituations":"Building a new PDF (e.g. assembling a multi-file document via the doc builder) in a long session; Safari's lower WASM ceiling; a bug that leaked document handles over time.","solutions":["Retry `PdfiumDocument.create()` once after `resetPdfiumModule()`.","Audit the doc-builder usage path for unclosed `PdfiumDocument` instances (ensure `dispose()`/close is always called).","Confirm `getPdfiumModule()` resolved fully (PDFiumExt_Init succeeded) before heavy builder work.","Reduce simultaneous live documents."],"exampleFix":"// before\nstatic async create(): Promise<PdfiumDocument> {\n  const m = await getPdfiumModule();\n  const docPtr = m.FPDF_CreateNewDocument();\n  if (!docPtr) throw new Error(\"PDFium: failed to create document\");\n  return new PdfiumDocument(m, docPtr);\n}\n\n// after\nstatic async create(): Promise<PdfiumDocument> {\n  let m = await getPdfiumModule();\n  let docPtr = m.FPDF_CreateNewDocument();\n  if (!docPtr) {\n    resetPdfiumModule();\n    m = await getPdfiumModule();\n    docPtr = m.FPDF_CreateNewDocument();\n  }\n  if (!docPtr) throw new Error(\"PDFium: failed to create document\");\n  return new PdfiumDocument(m, docPtr);\n}","handlingStrategy":"retry","validationCode":"// Ensure the module fully initialised (PDFiumExt_Init not swallowed) before builder work\nconst m = await getPdfiumModule();\nif (typeof m.PDFiumExt_OpenFileWriter !== \"function\") {\n  console.warn(\"PDFium extensions unavailable; builder may fail.\");\n}","typeGuard":null,"tryCatchPattern":"async function createDocWithRetry(): Promise<PdfiumDocument> {\n  try { return await PdfiumDocument.create(); }\n  catch (e) {\n    if (e instanceof Error && e.message.includes(\"failed to create document\")) {\n      resetPdfiumModule();\n      return await PdfiumDocument.create();\n    }\n    throw e;\n  }\n}","preventionTips":["Always dispose/close PdfiumDocument instances when done to avoid heap accumulation.","Retry `PdfiumDocument.create()` once after `resetPdfiumModule()`.","Confirm `getPdfiumModule()` resolved and extensions initialised before heavy builder work.","Reduce simultaneous live documents."],"tags":["pdfium","wasm","memory","doc-builder"],"backgroundTag":null,"analyzedSha":"9ef20dcab80b85041912f045e17a6aea1d08f969","analyzedAt":"2026-08-13T22:11:39.827Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}