⭐ How to Troubleshoot Installation

[zbjornson]

The majority of issues opened in node-canvas are for installation help. This post is an experiment to see if we can help users help themselves to troubleshoot installations.

Installation fails with a 404 in the log

If you have an ARM CPU, including an Apple M1 or M2

Prebuilds aren't available for ARM. Please see the wiki for guides on building from source. See also node-gfx/node-canvas-prebuilt#69.

If you're on Alpine Linux or another distro using musl-libc

The log may look like

node-pre-gyp WARN Tried to download(404): https://github.com/node-gfx/node-canvas-prebuilt/releases/download/v2.6.0/canvas-v2.6.0-node-v64-linux-musl-x64.tar.gz

Prebuilds are only available for glibc, not musl-libc. See node-gfx/node-canvas-prebuilt#77, which includes information on building from source.

If you're using Electron

The log may look like

node-pre-gyp WARN Tried to download(404): https://github.com/node-gfx/node-canvas-prebuilt/releases/download/v2.6.0/canvas-v2.6.0-electron-v3.0-win32-unknown-x64.tar.gz 
node-pre-gyp WARN Pre-built binaries not found for canvas@2.6.0 and electron@3.0.11 (electron-v3.0 ABI, unknown) (falling back to source compile with node-gyp)

There are no prebuilds available for Electron. Please see the wiki for guides on building from source. See also node-gfx/node-canvas-prebuilt#84 or #1467.

If a new version of Node.js was recently released

The log may look like

node-pre-gyp WARN Tried to download(404): https://github.com/node-gfx/node-canvas-prebuilt/releases/download/v2.6.0/canvas-v2.6.0-node-v79-win32-unknown-x64.tar.gz
node-pre-gyp WARN Pre-built binaries not found for canvas@2.6.0 and node@13.3.0 (node-v79 ABI, unknown) (falling back to source compile with node-gyp)

We manually publish prebuilt versions of node-canvas, and it can take some time for us to catch up.

You can see the list of available prebuilds here (expand the "Assets" section under the version you're trying to install): https://github.com/node-gfx/node-canvas-prebuilt/releases.

If you're using 32-bit Node.js

The log will include a 404 and ia32. Node-canvas does not readily compile on 32-bit platforms because the necessary dependencies are hard to obtain. Use 64-bit Node.js instead, especially because 32-bit Node.js is only experimentally supported by the Node foundation.

I get a permissions error (EACCES)

Possibly your node_modules or an npm or yarn cache or temp directory is owned by a different user. Review the error log to see what folder you don't have permission to access. See #1429 for an example, or any of these issues.

If you were trying to install with sudo, try without. (See issues.)

I get a NODE_MODULE_VERSION error

The log may look like

...was compiled against a different Node.js version using NODE_MODULE_VERSION 72.
This version of Node.js requires NODE_MODULE_VERSION 64. Please try re-compiling or
re-installing the module

This could mean you upgraded Node.js without re-installing canvas. Try running yarn or npm install again.

This can also happen if you're using Electron. The version of Node wrapped by Electron must match the version of Node that you used to build/install canvas.

Installation fails with lots of compiler errors, including ...was declared deprecated and/or no viable conversion and/or 'Handle' is not a member of 'v8'

You're probably trying to install an old version of node-canvas. Version 2.x is required for Node.js v6.x and later. Version 2.5.x or later is required for Node.js v12.x and later. Check if your package.json or lock file specifies an old version.

I get a the specified procedure could not be found error

If you have Sharp.js also installed, there's an incompatibility between their build of Cairo and our build of Cairo. See #930.

I get the error canvas.node is not a valid Win32 application.

This usually means you have 32-bit Node.js and 64-bit node-canvas, or vice versa. They must be the same (and you should prefer 64-bit over 32-bit). You can check this is the issue using the instructions in #1533 (comment). It can also mean you're trying to use the Linux or Mac build from Windows.

I get a GLIBC version error

If you installed Node.js with snaps

Error: /snap/core/current/lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.25'
not found (required by /lib/x86_64-linux-gnu/libuuid.so.1)

This can happen if you installed Node.js with snaps instead of apt/dpkg, and if the snap core has an older version of glibc. (Background: #1959.)

If you're on CentOS 7 or EL 7

error: /lib64/libc.so.6: version `GLIBC_2.18` not found (required by 
...(project_dir).../node_modules/_canvas@2.8.0@canvas/build/Release/librsvg-2.so.2)

CentOS 7 and EL 7 use GLIBC 2.17, but v2.8.0+ of node-canvas were prebuilt with v2.24 from Debian Stretch. That is the minimum version of glibc required to use node-canvas 2.8.0+. For now, a workaround is to use node-canvas 2.7.0, or build from source.

Module did not self-register

Node-canvas isn't compatible with worker threads yet, see #1394. Canvas needs to be ported from NAN to N-API (#923).

---

To keep this issue concise and on-topic, (1) comments asking for help will be deleted, please open a separate issue instead, (2) comments with suggestions for improving the troubleshooting are welcome and will be hidden after incorporating into this top post.

[ndtreviv]

@ndtreviv I have encountered the same issue as you mentioned, I am using the latest node version 12.19.1 though. Have you resolved the version conflict issue?

I did. I was using the module inside an electron app. Electron seems to run with its own version of node. In my case I had to find out what version of node electron was running, and rebuild the module to fit that version.
I did this by using node version manager (nvm) to install the same version of node that electron is bundled with and switched to that version before running the rebuild command.

[lostpebble]

If you have Sharp.js also installed, there's an incompatibility between their build of Cairo and our build of Cairo. See #930.

And on the sharp documentation:

The prebuilt binaries provided by canvas for Windows depend on the unmaintained GTK 2, last updated in 2011.

These conflict with the modern, up-to-date binaries provided by sharp.

If both modules are used in the same Windows process, the following error will occur:
The specified procedure could not be found.

So.. I'm wondering what the expected way forward is here? I've been using sharp for image processing and Paper.js which uses node-canvas for other vector processing on top of that. I need to use them both- but the discourse between these projects seems to imply this is now some kind of impasse?

I've spent the whole day trying to get my project to run and I'm facing the same error every time, wondering if I need to now make a choice between these dependencies and try and move on.