Cannot find module '../build/Release/canvas.node' on macOS

Error: Cannot find module '../build/Release/canvas.node' looks like a missing dependency, but the package is installed. The file it points to is the compiled native binary, and on macOS it was never built. I hit this while running a Jest suite that rendered images.

The build step for node-canvas failed, not the install

The Node canvas package (node-canvas) is a binding around the Cairo graphics library, so npm has to compile a native addon during install. bindings.js then loads that addon from build/Release/canvas.node. When the C libraries Cairo needs are missing, the compile step fails and the package still lands in node_modules, so nothing breaks until the first require. macOS does not ship those libraries, which is why the same project can install fine on a Linux CI box and fail on your laptop.

Install the native libraries with Homebrew, then reinstall

1. Install the native dependencies

   Run this in your terminal. It installs pkg-config, cairo, pango, libpng, jpeg, giflib, and librsvg:

   brew install pkg-config cairo pango libpng jpeg giflib librsvg

   The canvas module compiles against these on macOS, on Apple Silicon (M1 and later) and on Intel Macs.

2. Delete the stale node_modules

   A half-built canvas directory survives a plain npm i, so remove the whole tree first:

   rm -rf node_modules

3. Reinstall your Node packages

   Now install again, with the system libraries in place:

   npm i

   The canvas package rebuilds, this time producing build/Release/canvas.node.

That's it. Three commands.

Resources

1. I found this solution originally at Flavio’s blog.
2. There’s a related Github issue that you can find here.

tl;dr

If you're facing the Cannot find module '../build/Release/canvas.node' error on macOS, it's likely due to missing dependencies for the Node canvas package. Install the necessary packages using Homebrew, clear your node_modules, and reinstall your Node packages to resolve the issue.