diff --git a/docs/_sidebar.md b/docs/_sidebar.md index b29bbaef53..6cbe725286 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -34,6 +34,7 @@ - [FAQ](faq.md) - [License](license.md) + - [Troubleshooting](troubleshooting.md) - Links diff --git a/docs/quick-start.md b/docs/quick-start.md index dcbe98886c..0c33cafbe8 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -39,3 +39,5 @@ docker run -it --rm \ More information about the Docker setup can be found in the README file of the [Docker Image](https://github.com/n8n-io/n8n/blob/master/docker/images/n8n/README.md). + +In case you run into issues, check out the [troubleshooting](troubleshooting.md) page or ask for help in the community [forum](https://community.n8n.io/). diff --git a/docs/setup.md b/docs/setup.md index c551395517..27e65e54ea 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -31,3 +31,5 @@ To use it, simply start n8n with `--tunnel` ```bash n8n start --tunnel ``` + +In case you run into issues, check out the [troubleshooting](troubleshooting.md) page or ask for help in the community [forum](https://community.n8n.io/). diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000000..7e6b4b058b --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,58 @@ +# Troubleshooting + +## Windows + +If you are experiencing issues running n8n with the typical flow of: + +```powershell +npx n8n +``` + +### Requirements + +Please ensure that you have the following requirements fulfilled: + +- Install latest version of [NodeJS](https://nodejs.org/en/download/) +- Install [Python 2.7](https://www.python.org/downloads/release/python-2717/) (It is okay to have multiple versions installed on the machine) +- Windows SDK +- C++ Desktop Development Tools +- Windows Build Tools + +#### Install build tools + +If you haven't satisfied the above, follow this procedure through your PowerShell (run with administrative privileges). +This command installs the build tools, windows SDK and the C++ development tools in one package. + +```powershell +npm install --global --production windows-build-tools +``` + +#### Configure npm to use Python version 2.7 + +```powershell +npm config set python python2.7 +``` + +#### Configure npm to use correct msvs version + +```powershell +npm config set msvs_version 2017 --global +``` + +### Lesser known issues: + +#### mmmagic npm package when using MSbuild tools with Visual Studio + +While installing this package, `node-gyp` is run and it might fail to install it with an error appearing in the ballpark of: + +``` +gyp ERR! stack Error: spawn C:\Program Files (x86)\Microsoft Visual Studio\2019\**Enterprise**\MSBuild\Current\Bin\MSBuild.exe ENOENT +``` + +It is seeking the `MSBuild.exe` in a directory that does not exist. If you are using Visual Studio Community or vice versa, you can change the path of MSBuild with command: + +```powershell +npm config set msbuild_path "C:\Program Files (x86)\Microsoft Visual Studio\2019\**Community**\MSBuild\Current\Bin\MSBuild.exe" +``` + +Attempt to install package again after running the command above.