n8n PDF Loader 'DOMMatrix is not defined' - Diagnosis and Action Plan

Problem summary: When the Default Data Loader node attempts to process a PDF binary, execution fails with "DOMMatrix is not defined" and container logs show failed native bindings for @napi-rs/canvas and warnings about polyfilling DOMMatrix/ImageData. This indicates the node relies on browser-like canvas APIs that are unavailable in the execution runtime.

Technical significance: PDF rendering libraries frequently depend on canvas and DOM primitives for measurement and rasterization. In server/node environments, these primitives must be provided either by native bindings (e.g., @napi-rs/canvas, node-canvas) or robust polyfills that simulate DOMMatrix/ImageData. The error and binding failure suggest the container image lacks compiled native dependencies (libcairo, libpango, etc.) or the node module failed to load because it wasn't built for the runtime's architecture.

Recommended remediation steps for engineers: 1) Ensure native libraries are installed in the runtime/container (cairo, pango, libjpeg, giflib). 2) Rebuild or install @napi-rs/canvas for the target architecture (or use an official n8n image that includes canvas support). 3) If native bindings are unacceptable, consider switching to a server-side PDF parser that doesn't rely on canvas (pdf-lib, pdfjs-dist with headless-Canvas polyfills), or process PDFs using a dedicated microservice (Python/Poppler) that returns structured data to n8n.

Operational guidance for leaders: Addressing this requires coordination between application, DevOps, and security teams to allow additional native libs in production images. For product owners, document SLAs and supported file types clearly to reduce user friction. If providing a managed n8n Cloud, consider offering a managed PDF-processing add-on or ensuring images include tested native bindings to eliminate this common friction point.