{"record":{"id":"33b1302748446426","repo":"Stirling-Tools/Stirling-PDF","slug":"pdfium-failed-to-set-image-matrix","errorCode":null,"errorMessage":"PDFium: failed to set image matrix","messagePattern":"PDFium: failed to set image matrix","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"frontend/editor/src/core/utils/imageToPdfUtils.ts","lineNumber":152,"sourceCode":"        throw new Error(\"PDFium: failed to set bitmap on image object\");\n      }\n\n      // Set transformation matrix: scale + translate\n      // FS_MATRIX: {a, b, c, d, e, f} — 6 floats\n      const matrixPtr = m.pdfium.wasmExports.malloc(6 * 4);\n      m.pdfium.setValue(matrixPtr, drawWidth, \"float\"); // a = scaleX\n      m.pdfium.setValue(matrixPtr + 4, 0, \"float\"); // b\n      m.pdfium.setValue(matrixPtr + 8, 0, \"float\"); // c\n      m.pdfium.setValue(matrixPtr + 12, drawHeight, \"float\"); // d = scaleY\n      m.pdfium.setValue(matrixPtr + 16, drawX, \"float\"); // e = translateX\n      m.pdfium.setValue(matrixPtr + 20, drawY, \"float\"); // f = translateY\n\n      const setMatrixOk = m.FPDFPageObj_SetMatrix(imageObjPtr, matrixPtr);\n      m.pdfium.wasmExports.free(matrixPtr);\n\n      if (!setMatrixOk) {\n        m.FPDFPageObj_Destroy(imageObjPtr);\n        throw new Error(\"PDFium: failed to set image matrix\");\n      }\n\n      // Insert image into page\n      m.FPDFPage_InsertObject(pagePtr, imageObjPtr);\n\n      // Generate page content stream\n      m.FPDFPage_GenerateContent(pagePtr);\n      m.FPDF_ClosePage(pagePtr);\n\n      // Save document\n      const pdfBytes = await saveRawDocument(docPtr);\n      const pdfFilename = imageFile.name.replace(/\\.[^.]+$/, \".pdf\");\n\n      return new File([pdfBytes], pdfFilename, { type: \"application/pdf\" });\n    } finally {\n      m.FPDF_CloseDocument(docPtr);\n    }\n  } catch (error) {","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/Stirling-Tools/Stirling-PDF/blob/9ef20dcab80b85041912f045e17a6aea1d08f969/frontend/editor/src/core/utils/imageToPdfUtils.ts#L134-L170","documentation":"Thrown when FPDFPageObj_SetMatrix(imageObjPtr, matrixPtr) returns falsy after the bitmap was successfully set on the image object. The matrix (scale + translate, 6 floats on the WASM heap) positions the image on the page; if PDFium rejects it, the image cannot be placed correctly. The image object is destroyed before throwing to avoid a leak.","triggerScenarios":"All prior steps (document, page, bitmap, image object, set-bitmap) succeeded but the matrix set returns 0. Possible causes: non-finite (NaN/Infinity) values in drawWidth/drawHeight/drawX/drawY fed into the matrix, or a PDFium internal error for the given transform.","commonSituations":"A zero-aspect or corrupt image produced NaN/Infinity in the aspect-ratio math (e.g. division by imageWidth or imageHeight that is 0), which then propagates into the matrix floats. stretchToFit logic computed non-finite draw dimensions.","solutions":["Validate that imageWidth and imageHeight are finite and non-zero before computing drawWidth/drawHeight/drawX/drawY.","Guard the aspect-ratio division (imageAspectRatio = imageWidth / imageHeight) against divide-by-zero.","Clamp matrix values to finite numbers before writing them to the WASM heap.","Test with a known-good image to isolate whether the input or the transform math is at fault."],"exampleFix":"// before\nconst imageAspectRatio = imageWidth / imageHeight; // NaN if height is 0\n// after\nconst imageAspectRatio = imageHeight > 0 ? imageWidth / imageHeight : 1;\nif (!Number.isFinite(drawWidth) || !Number.isFinite(drawHeight)) throw new Error('Invalid image dimensions');","handlingStrategy":"validation","validationCode":"function areFiniteDrawValues(dw: number, dh: number, dx: number, dy: number): boolean {\n  return [dw, dh, dx, dy].every(v => Number.isFinite(v)) && dw > 0 && dh > 0;\n}\n// After computing drawWidth/drawHeight/drawX/drawY, validate before writing the matrix.","typeGuard":"function isFiniteMatrix(a: number, b: number, c: number, d: number, e: number, f: number): boolean {\n  return [a, b, c, d, e, f].every(Number.isFinite);\n}","tryCatchPattern":"try {\n  await convertImageToPdf(file);\n} catch (e) {\n  const reason = (e as Error & { cause?: Error }).cause?.message ?? e.message;\n  if (reason.includes('failed to set image matrix')) {\n    showUser('The image dimensions are invalid for PDF layout. Try a different image or page format.');\n  } else { throw e; }\n}","preventionTips":["Guard the aspect-ratio division against divide-by-zero (imageHeight === 0).","Validate decoded image dimensions are finite and positive before layout math.","Clamp drawWidth/drawHeight/drawX/drawY to finite values before setting the matrix.","Reject zero-byte or corrupt images that yield zero dimensions."],"tags":["image-to-pdf","pdfium","wasm","matrix","transform"],"backgroundTag":null,"analyzedSha":"9ef20dcab80b85041912f045e17a6aea1d08f969","analyzedAt":"2026-08-13T22:11:39.827Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}