⭐ How to Troubleshoot Installation

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

We may not have prebuilt binaries for your platform. Have you read the [installation instructions](https://github.com/Automattic/node-canvas?tab=readme-ov-file#installation)?

### If you're on Alpine Linux or another distro using [musl-libc](https://www.musl-libc.org/)
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 https://github.com/node-gfx/node-canvas-prebuilt/issues/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](https://github.com/Automattic/node-canvas/wiki#installation-guides) for guides on building from source. See also https://github.com/node-gfx/node-canvas-prebuilt/issues/84 or https://github.com/Automattic/node-canvas/issues/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](https://github.com/Automattic/node-canvas/issues?utf8=%E2%9C%93&q=is%3Aissue+eacces).

If you were trying to install with `sudo`, try without. (See [issues](https://github.com/Automattic/node-canvas/issues?utf8=%E2%9C%93&q=is%3Aissue+sudo).)

## 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 https://github.com/Automattic/node-canvas/issues/1533#issuecomment-619580233. 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.