Skip to content

Commit

Permalink
Merge pull request #2454 from nschonni/troubleshooting-edits
Browse files Browse the repository at this point in the history 
Troubleshooting edits
  • Loading branch information
@nschonni
nschonni committed Dec 16, 2018
2 parents 454bb8e + e8f6b85 commit 7c1dd8e
Showing 1 changed file with 81 additions and 65 deletions.
146 changes: 81 additions & 65 deletions TROUBLESHOOTING.md
View file
@@ -1,11 +1,12 @@
# Troubleshooting

This document covers some common node-sass issues and how to resolve them. You should always follow these steps before opening a new issue.
This document covers some common node-sass issues and how to resolve them. You
should always follow these steps before opening a new issue.

## TOC

- [Installation problems](#installation-problems)
- [404 downloading binding.node file](#404-downloading-bindingnode-file)
- [404 downloading binding.node file](#404s)
- [Assertion failed: (handle->flags & UV_CLOSING), function uv__finish_close](#assertion-failed-handle-flags-&-uv_closing-function-uv__finish_close)
- [Cannot find module '/root/<...>/install.js'](#cannot-find-module-rootinstalljs)
- [Linux](#linux)
Expand All @@ -19,43 +20,52 @@ This document covers some common node-sass issues and how to resolve them. You s
- [Using node-sass with Visual Studio 2015 Task Runner.](#using-node-sass-with-visual-studio-2015-task-runner)
- [Installing node-sass 4.x with Node < 4](#installing-node-sass-4x-with-node--4)

## Installation problems
## Installation

### 404 downloading binding.node file
### 404s

If you see a 404 when trying to install node-sass, this indicates that your trying
to install a version of node-sass that doesn't support your version of NodeJS, or
uses an alternate V8 environment (Meteor, Electron, etc...) that isn't supported
by node-sass.
If you encounter this, please check what version of NodeJs you're running (`node -v`)
and check for a supported version of node-sass for your NodeJs by checking our
[release page](https://github.com/sass/node-sass/releases).

### Assertion failed: (handle->flags & UV_CLOSING), function uv__finish_close
```console
> node-sass@4.6.1 install /src/node_modules/node-sass
> node scripts/install.js

This issue primarily affected early node-sass@3.0.0 alpha and beta releases, although it did occassionally happen in node-sass@2.x.
Downloading binary from https://github.com/sass/node-sass/releas…
Cannot download "https://github.com/sass/node-sass/releas…":

The only fix for this issue is to update to node-sass >= 3.0.0.
HTTP error 404 Not Found
```

If this didn't solve your problem please open an issue with the output from [our debugging script](#debugging-installation-issues).
If you encounter this, please check what version of NodeJs you're running (`node -v`)
and check for a supported version of node-sass for your NodeJs by checking our
[release page](https://github.com/sass/node-sass/releases).

### Proxy issues

### Cannot find module '/root/<...>/install.js'
If you work in behind a corporate proxy try setting the proxy variables. The
following is a [guide for setting this up](https://jjasonclark.com/how-to-setup-node-behind-web-proxy/).

#### Linux
### Running with sudo or as root

This can happen if you are install node-sass as `root`, or globally with `sudo`. This is a security feature of `npm`. You should always avoid running `npm` as `sudo` because install scripts can be unintentionally malicious.
This can happen if you are install node-sass as `root`, or globally with `sudo`.
This is a security feature of `npm`. You should always avoid running `npm` as
`sudo` because install scripts can be unintentionally malicious.
Please check [npm documentation on fixing permissions](https://docs.npmjs.com/getting-started/fixing-npm-permissions).

If you must however, you can work around this error by using the `--unsafe-perm` flag with npm install i.e.
If you must however, you can work around this error by using the `--unsafe-perm`
flag with npm install i.e.

```sh
$ sudo npm install --unsafe-perm -g node-sass
sudo npm install --unsafe-perm -g node-sass
```

If this didn't solve your problem please open an issue with the output from [our debugging script](#debugging-installation-issues).
If this didn't solve your problem please open an issue with the output from
[our debugging script](#debugging-installation-issues).

### npm 5
### npm

Some users upgrading from previous versions of npm before 5 have found conflicts with
old lock file formats. This may be show up as a URL instead of the actual version
Expand All @@ -77,57 +87,48 @@ npm cache clean
npm install
```

## Glossary


### Which node runtime am I using?

There are two primary node runtimes, Node.js and io.js, both of which are supported by node-sass. To determine which you are currently using you first need to determine [which node runtime](#which-node-runtime-am-i-using-glossaryruntime) you are running.

```
node -v
```

If the version reported begins with a `0`, you are running Node.js, otherwise you are running io.js.
## Helping us, help you

### Find what version of Node you're running

### Which version of node am I using?
To determine which version of Node.js or io.js you are currently using run the
following command in a terminal.

To determine which version of Node.js or io.js you are currenty using run the following command in a terminal.

```
```console
node -v
```

The resulting value the version you are running.

### Debugging installation issues

### Debugging installation issues.

Node sass runs some install scripts to make it as easy to use as possible, but some times there can be issues. Before opening a new issue please follow the instructions for [Windows](#windows) or [Linux/OSX](#linuxosx) and provide their output in you [GitHub issue](https://github.com/sass/node-sass/issues).
Node sass runs some install scripts to make it as easy to use as possible, but
some times there can be issues. Before opening a new issue please follow the
instructions for [Windows](#windows) or [Linux/OSX](#linuxosx) and provide
their output in you [GitHub issue](https://github.com/sass/node-sass/issues).

**Remember to always search before opening a new issue**.

#### Windows

Firstly create a clean work space.

```sh
```console
mkdir \temp1
cd \temp1
```

Check your `COMSPEC` environment variable.

```sh
```console
node -p process.env.comspec
```

Please make sure the variable points to `C:\WINDOWS\System32\cmd.exe`

Gather some basic diagnostic information.

```sh
```console
npm -v
node -v
node -p process.versions
Expand All @@ -137,64 +138,68 @@ node -p process.arch

Clean npm cache

```sh
```console
npm cache clean
```

Install the latest node-sass

```sh
npm install -ddd node-sass > npm.log 2> npm.err
```console
npm install node-sass@latest
```

Note which version was installed by running

```sh
```console
npm ls node-sass
```
```sh

```console
y@1.0.0 /tmp
└── node-sass@3.8.0
```

If node-sass could not be installed successfully, please publish your `npm.log`
If node-sass couldn't be installed successfully, please publish your `npm.log`
and `npm.err` files for analysis.

You can [download reference known-good logfiles](https://gist.github.com/saper/62b6e5ea41695c1883e3)
to compare your log against.

If node-sass install successfully lets gather some basic installation infomation.
If node-sass install successfully lets gather some basic installation information.

```sh
```console
node -p "require('node-sass').info"
```
```sh

```console
node-sass 3.8.0 (Wrapper) [JavaScript]
libsass 3.3.6 (Sass Compiler) [C/C++]
```

If the node-sass installation process produced an error, open the vendor folder.

```sh
```console
cd node_modules\node-sass\vendor
```

Then, using the version number we gather at the beginning, go to `https://github.com/sass/node-sass/releases/tag/v<your-version>`.

There you should see a folder with same name as the one in the `vendor` folder. Download the `binding.node` file from that folder and replace your own with it.
There you should see a folder with same name as the one in the `vendor` folder.
Download the `binding.node` file from that folder and replace your own with it.

Test if that worked by gathering some basic installation infomation.
Test if that worked by gathering some basic installation information.

```sh
```console
node -p "require('node-sass').info"
```
```sh

```console
node-sass 3.8.0 (Wrapper) [JavaScript]
libsass 3.3.6 (Sass Compiler) [C/C++]
```

If this still produces an error please open an issue with the output from these steps.

If this still produces an error please open an issue with the output from these
steps.

#### Linux/OSX

Expand All @@ -218,24 +223,26 @@ node -p process.arch
Install the latest node-sass

```sh
npm install node-sass
npm install node-sass@latest
```

Note which version was installed by running

```sh
npm ls node-sass
```

```sh
y@1.0.0 /tmp
└── node-sass@3.8.0
```

If node-sass install successfully lets gather some basic installation infomation.
If node-sass install successfully lets gather some basic installation information.

```sh
node -p "require('node-sass').info"
```

```sh
node-sass 3.8.0 (Wrapper) [JavaScript]
libsass 3.3.6 (Sass Compiler) [C/C++]
Expand All @@ -249,26 +256,35 @@ cd node_modules/node-sass/vendor

Then, using the version number we gather at the beginning, go to `https://github.com/sass/node-sass/releases/tag/v<your-version>`.

There you should see a folder with same name as the one in the `vendor` folder. Download the `binding.node` file from that folder and replace your own with it.
There you should see a folder with same name as the one in the `vendor` folder.
Download the `binding.node` file from that folder and replace your own with it.

Test if that worked by gathering some basic installation infomation.
Test if that worked by gathering some basic installation information.

```sh
node -p "require('node-sass').info"
```

```sh
node-sass 3.8.0 (Wrapper) [JavaScript]
libsass 3.3.6 (Sass Compiler) [C/C++]
```

If this still produces an error please open an issue with the output from these steps.
If this still produces an error please open an issue with the output from these
steps.

### Using node-sass with Visual Studio 2015 Task Runner.
### Using node-sass with Visual Studio 2015 Task Runner

If you are using node-sass with VS2015 Task Runner Explorer, you need to make sure that the version of node.js (or io.js) is same as the one you installed node-sass with. This is because for each node.js runtime modules version (`node -p process.versions.modules`), we have a separate build of native binary. See [#532](https://github.com/sass/node-sass/issues/532).
If you are using node-sass with VS2015 Task Runner Explorer, you need to make
sure that the version of node.js is same as the one you installed node-sass
with. This is because for each node.js runtime modules version (`node -p process.versions.modules`)
, we have a separate build of native binary. See [#532](https://github.com/sass/node-sass/issues/532).

Alternatively, if you prefer using system-installed node.js (supposedly higher version than one bundles with VS2015), you may want to point Visual Studio 2015 to use it for task runner jobs by following the guidelines available at: http://blogs.msdn.com/b/webdev/archive/2015/03/19/customize-external-web-tools-in-visual-studio-2015.aspx.
Alternatively, if you prefer using system-installed node.js (supposedly higher
version than one bundles with VS2015), you may want to point Visual Studio 2015
to use it for task runner jobs by [following the guidelines](http://blogs.msdn.com/b/webdev/archive/2015/03/19/customize-external-web-tools-in-visual-studio-2015.aspx).

### Installing node-sass 4.x with Node < 4

See the discussion in [this comment](https://github.com/sass/node-sass/issues/2100#issuecomment-334651235) for a workaround. As of node-sass@v5 only Node 6 and above will be offically supported.
See the discussion in [this comment](https://github.com/sass/node-sass/issues/2100#issuecomment-334651235)
for a workaround. As of node-sass@v5 only Node 6 and above will be officially supported.

0 comments on commit 7c1dd8e

Please sign in to comment.