Stirling-Tools/Stirling-PDF · critical · Error

PDFium: failed to set image matrix

Error message

PDFium: failed to set image matrix

What it means

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.

Source

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

        throw new Error("PDFium: failed to set bitmap on image object");
      }

      // Set transformation matrix: scale + translate
      // FS_MATRIX: {a, b, c, d, e, f} — 6 floats
      const matrixPtr = m.pdfium.wasmExports.malloc(6 * 4);
      m.pdfium.setValue(matrixPtr, drawWidth, "float"); // a = scaleX
      m.pdfium.setValue(matrixPtr + 4, 0, "float"); // b
      m.pdfium.setValue(matrixPtr + 8, 0, "float"); // c
      m.pdfium.setValue(matrixPtr + 12, drawHeight, "float"); // d = scaleY
      m.pdfium.setValue(matrixPtr + 16, drawX, "float"); // e = translateX
      m.pdfium.setValue(matrixPtr + 20, drawY, "float"); // f = translateY

      const setMatrixOk = m.FPDFPageObj_SetMatrix(imageObjPtr, matrixPtr);
      m.pdfium.wasmExports.free(matrixPtr);

      if (!setMatrixOk) {
        m.FPDFPageObj_Destroy(imageObjPtr);
        throw new Error("PDFium: failed to set image matrix");
      }

      // Insert image into page
      m.FPDFPage_InsertObject(pagePtr, imageObjPtr);

      // Generate page content stream
      m.FPDFPage_GenerateContent(pagePtr);
      m.FPDF_ClosePage(pagePtr);

      // Save document
      const pdfBytes = await saveRawDocument(docPtr);
      const pdfFilename = imageFile.name.replace(/\.[^.]+$/, ".pdf");

      return new File([pdfBytes], pdfFilename, { type: "application/pdf" });
    } finally {
      m.FPDF_CloseDocument(docPtr);
    }
  } catch (error) {

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Validate that imageWidth and imageHeight are finite and non-zero before computing drawWidth/drawHeight/drawX/drawY.
2. Guard the aspect-ratio division (imageAspectRatio = imageWidth / imageHeight) against divide-by-zero.
3. Clamp matrix values to finite numbers before writing them to the WASM heap.
4. Test with a known-good image to isolate whether the input or the transform math is at fault.

Example fix

// before
const imageAspectRatio = imageWidth / imageHeight; // NaN if height is 0
// after
const imageAspectRatio = imageHeight > 0 ? imageWidth / imageHeight : 1;
if (!Number.isFinite(drawWidth) || !Number.isFinite(drawHeight)) throw new Error('Invalid image dimensions');

function areFiniteDrawValues(dw: number, dh: number, dx: number, dy: number): boolean {
  return [dw, dh, dx, dy].every(v => Number.isFinite(v)) && dw > 0 && dh > 0;
}
// After computing drawWidth/drawHeight/drawX/drawY, validate before writing the matrix.

function isFiniteMatrix(a: number, b: number, c: number, d: number, e: number, f: number): boolean {
  return [a, b, c, d, e, f].every(Number.isFinite);
}

try {
  await convertImageToPdf(file);
} catch (e) {
  const reason = (e as Error & { cause?: Error }).cause?.message ?? e.message;
  if (reason.includes('failed to set image matrix')) {
    showUser('The image dimensions are invalid for PDF layout. Try a different image or page format.');
  } else { throw e; }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• PDFium: failed to create document
• PDFium: failed to create page
• PDFium: failed to create bitmap
• PDFium: failed to create image object
• PDFium: failed to set bitmap on image object

AI-assisted analysis of Stirling-Tools/Stirling-PDF@9ef20dcab8 (2026-08-13). Data as JSON: /api/errors/33b1302748446426. Report an issue: GitHub.