Node.js Troubleshooting

This document is designed to assist developers using the ServBay local development environment in resolving common issues that may arise when working with Node.js packages.

Node.js / npm / pnpm / yarn Command Version Not Found

When using Node.js, npm, pnpm, or yarn within ServBay, you may encounter error messages like the following, indicating that the system cannot find the specific version of the Node.js executable you are attempting to use:

Warning: Specified Node.js version '22' for 'node' not found.
If this is not your intention, please delete the 'NODE_VERSION' configuration
from the '.servbay.config' file in the current directory.

This usually happens because the specific version of Node.js you intend to use is not yet installed in ServBay, or you want to use a Node.js version managed by another tool such as nvm or homebrew, but due to environment configuration issues, ServBay cannot locate them correctly.

Tip

After installing ServBay, the system sets up script aliases that prioritize using ServBay-installed Node.js packages. If ServBay cannot find the specified version, it will then fall back to the default version installed via nvm, and finally to the version installed via homebrew. If none are found, you will see the error message above.

Analysis:

1. The Node.js version you are trying to use has not been installed within the ServBay application.
2. The system has nvm or homebrew installed, and you expect to use a Node.js version managed through these, but incorrect shell environment configuration (especially with the PATH or NVM_BIN variables) prevents ServBay from finding these external Node.js installations.

Solution:

If you have already installed nvm and have used it to install a Node.js version but are still seeing this error, a common reason is a missing or incorrectly set NVM_BIN environment variable in your shell configuration. When nvm is properly installed, this variable is set automatically and points to the location of the Node.js executables managed by nvm, which is essential for nvm to function correctly.

Simply check and correct the nvm-related configuration in your shell configuration files (such as ~/.zshrc, ~/.bash_profile, etc.), ensure the NVM_BIN variable is properly set and exported, then reload your configuration (for example, by running source ~/.zshrc or restarting your terminal). After fixing this, ServBay should be able to correctly fall back to the Node.js version managed by nvm.

If you don't use nvm or homebrew, or you prefer to use the Node.js versions managed by ServBay, simply ensure that the Node.js version you want to use is installed from the "Packages" section within the ServBay application.

Unsupported Architecture Error When Using npm Packages like node-sass

macOS users on Apple Silicon chips (M1/M2/M3/M4 Arm64 architecture) may encounter errors such as Unsupported architecture (arm64) when using certain older or native-module-dependent npm packages, such as node-sass. This happens because these legacy packages often only provide binaries or build configurations for x86_64 architecture.

ERROR: Module Error (from ./node_modules/sass-loader/dist/cjs.js):
Node Sass does not yet support your current environment: OS X Unsupported architecture (arm64) with Node.js 14.x
For more information on which environments are supported
please see:
https://github.com/sass/node-sass/releases/tag/v4.14.1

Analysis:

Some npm packages include components written in C++ or other native languages that require compilation for a specific CPU architecture. Older versions of such packages may not provide prebuilt binaries or support for Arm64 architecture (such as Apple Silicon).

Solutions:

1. Switch to a Modern, Arm64-Compatible Alternative (Recommended):

   The best and recommended solution is to replace outdated packages with modern alternatives that fully support Arm64. For example, swap out the legacy and less-maintained node-sass package with the actively maintained and more robust sass package. Most modern frontend projects and tooling have already migrated to using sass.

   npm uninstall node-sass
   npm install --save-dev sass

2. Install the x86_64 Architecture Version of Node.js in ServBay and Run via Rosetta 2 (Not Recommended):

   ServBay supports installing the x86_64 architecture version of Node.js. On Apple Silicon Macs, this allows you to run Node.js and its x86_64 native module dependencies via the macOS Rosetta 2 translation layer. You can install the x86_64 version of Node.js from the "Packages" section in the ServBay application.

   

   Note: This is generally not recommended as a long-term solution. It relies on Rosetta 2 emulation, which may introduce performance overhead and potential compatibility issues compared to running natively on Arm64. Wherever possible, prefer Solution 1 above.

---