Troubleshooting your Development Environment Setup

If you see an error similar to the following:

(STDERR) Error: The babel-runtime npm package could not be found in your node_modules
(STDERR) directory. Please run the following command to install it:
(STDERR)
(STDERR)   meteor npm install --save babel-runtime
(STDERR)
(...)
=> Exited with code: 1
=> Your application is crashing. Waiting for file change.

Install the missing package using the command below:

meteor npm install --save babel-runtime

If you see a warning similar to the following in the meteor logs:

(STDERR) Note: you are using a pure-JavaScript implementation of bcrypt.
(STDERR) While this implementation will work correctly, it is known to be
(STDERR) approximately three times slower than the native implementation.
(STDERR) In order to use the native implementation instead, run
(STDERR)
(STDERR)   meteor npm install --save bcrypt
(STDERR)

Cause: The native bcrypt library is not installed. Meteor falls back to a pure JavaScript implementation, which is significantly slower.

Solution: Install the native library:

meteor npm install --save bcrypt

If you encounter an error similar to the following:

gyp ERR! configure error
gyp ERR! stack Error: Python executable "/usr/local/bin/python3" is v3.5.2, which is not supported by gyp.
gyp ERR! stack You can pass the --python switch to point to Python >= v2.5.0 & < 3.0.0.

Cause: The Python version configured for npm is not supported by node-gyp.

Supported versions:

• >= 2.5.0

• < 3.0.0

Solution: If a compatible Python version is installed, configure it with:

meteor npm config set python python2.7

Then rebuild the project:

meteor npm install --save bcrypt

Verify the installation by confirming output similar to the following:

> node-gyp rebuild

  CXX(target) Release/obj.target/bcrypt_lib/src/blowfish.o
  CXX(target) Release/obj.target/bcrypt_lib/src/bcrypt.o
  CXX(target) Release/obj.target/bcrypt_lib/src/bcrypt_node.o
  SOLINK_MODULE(target) Release/bcrypt_lib.node
clang: warning: libstdc++ is deprecated; move to libc++ with a minimum deployment target of OS X 10.9
Rocket.Chat@0.46.0-develop /Users/douglas/work/github/Rocket.Chat
└─┬ bcrypt@0.8.7
  ├── bindings@1.2.1
  └── nan@2.3.5

Please follow these steps if you encounter the error message, “/sbin/ldconfig.real: /usr/lib/wsl/lib/libcuda.so.1 is not a symbolic link” while building your Rocket.Chat project.

1. Open a terminal and check the status of the libcuda.so.1 file by running:

   ls -l /usr/lib/wsl/lib/libcuda.so.1

   If the output shows this:

   -r-xr-xr-x 1 root root 154088 Dec 19  2023 /usr/lib/wsl/lib/libcuda.so.1

   This means the libcuda.so.1 file exists but is not a symbolic link, as indicated by the file permissions and type (-r-xr-xr-x indicates a regular file, not a symbolic link). To resolve this issue, remove this file and create a symbolic link pointing to the correct libcuda.so file.

2. Remove libcuda.so.1 file:

   sudo rm /usr/lib/wsl/lib/libcuda.so.1

3. Check for the actual libcuda files in the directory to determine the correct target for the symbolic link:

   ls -l /usr/lib/wsl/lib/

   Look for the actual libcuda files, such as libcuda.so.1.1.

4. Create a symbolic link, assuming libcuda.so.1.1 is the correct target file:

   sudo ln -s /usr/lib/wsl/lib/libcuda.so.1.1 /usr/lib/wsl/lib/libcuda.so.1

5. Verify the symbolic link is set up correctly:

   ls -l /usr/lib/wsl/lib/libcuda.so.1

   The output should show that libcuda.so.1 is a symbolic link pointing to libcuda.so.1.1 (or another appropriate version):

   lrwxrwxrwx 1 root root 31 Jun 24 19:04 /usr/lib/wsl/lib/libcuda.so.1 -> /usr/lib/wsl/lib/libcuda.so.1.1

6. Clean Yarn cache:

   yarn cache clean

7. Install dependencies and build the project:

   yarn
   yarn dsv

This error is typically caused by insufficient memory or CPU resources allocated to WSL, which can lead to segmentation faults during the build process. You can resolve it by following these steps:

1. Allocate more memory and CPU cores by editing the .wslconfig file. To do this:

   1. Open the Windows Run dialog (Win + R) and run:

notepad %UserProfile%\.wslconfig

2. You can replace notepad with code to use Visual Studio Code.

3. If the file does not exist, create it.

4. Add or update the following configuration:

[wsl2]
memory=4GB        # Increase to 8GB or more if available
processors=2      # Adjust based on your system

2. After saving the file, restart WSL to apply the changes:

wsl --shutdown

Then launch your WSL distribution again.

3. Corrupted local build files can sometimes trigger segmentation faults.

cd Rocket.Chat/apps/meteor
rm -rf .meteor/local

4. Clean the project and rebuild:

cd Rocket.Chat
rm -rf node_modules
yarn cache clean
yarn
yarn dsv

If the error persists, try allocating at least 8GB of memory to WSL.

This error typically occurs when the current user lacks write permissions for the Yarn cache directory (~/.yarn).

Confirm the error resembles:

EACCES: permission denied

Run the following commands to restore ownership and write access:

sudo chown -R $(whoami) ~/.yarn
sudo chmod -R u+w ~/.yarn

If yarn fails during the fibers linking step with an error similar to:

YN0009: fibers@npm:5.0.3 couldn't be built successfully (exit code 1)

npm install node-gyp --global

node-gyp introduced breaking changes in v10.0.0 and supports Node.js ^16.14.0 || >=18.0.0. If you encounter Node version compatibility issues, install node-gyp@9.4.1 or earlier.

See the release notes for more details.

2. Rebuild fibers for the ARM64 architecture:

cd node_modules/fibers
node-gyp rebuild --arch=arm64

Depending on your node-gyp version, the deprecated distutils package may be required.

Since distutils was removed in Python 3.12+, use an earlier Python version if you encounter related errors.

3. Copy the compiled binary to the expected location:

mkdir bin/darwin-arm64-83
cp build/Release/fibers.node bin/darwin-arm64-83/fibers.node

4. Replace the existing module inside Meteor:

cd ../..
rm -rf apps/meteor/node_modules/fibers/
cp -r node_modules/fibers apps/meteor/node_modules/

5. Complete the setup. Follow the instructions for resolving the bcrypt issue, even if the error has not yet appeared, to prevent additional build failures.

If you encounter an error similar to the following:

(mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64e')),
'/usr/local/lib/bcrypt_lib.node' (no such file)

1. Navigate to the bcrypt directory and rebuild the binary:

cd node_modules/bcrypt
make

This compiles the module for your system’s architecture.

2. After rebuilding, copy the updated module into the Meteor project:

cd ../..
rm -rf apps/meteor/node_modules/bcrypt
cp -r node_modules/bcrypt apps/meteor/node_modules/

If yarn dsv fails with an error similar to “Something went wrong installing the 'sharp' module”

this typically indicates an Apple Silicon compatibility issue. The sharp module, used for image processing in Rocket.Chat, cannot locate the required native binary (sharp-darwin-arm64v8.node).

Follow the steps below to resolve the issue:

1. Run the following command to install Rosetta 2, which enables x86_64 binaries to run on Apple Silicon:

softwareupdate --install-rosetta

2. Remove the existing Meteor installation:

sudo rm /usr/local/bin/meteor
rm -rf ~/.meteor

This ensures that any incompatible binaries are fully removed before reinstalling.

3. Reinstall Meteor using x86_64 architecture:

arch -x86_64 npm install -g meteor

Installing Meteor under x86_64 allows native modules like sharp to compile correctly.

4. Rebuild the project:

yarn && yarn build && yarn dsv

Once the process completes successfully, the application should be available at:

http://localhost:3000

If you encounter an error similar to the following:

(mach-o file, but is an incompatible architecture (have 'arm64', need 'x86_64'))

rm -rf ~/.meteor
npx meteor

After reinstalling, rerun your project to confirm the issue is resolved.