---
title: "Rocket Chat Dev Environment Troubleshooting"
slug: "troubleshooting-development-environment-setup"
description: "Resolve common Rocket Chat dev environment issues. Fix setup problems and ensure secure communication workflows run smoothly."
updated: 2026-02-13T13:51:19Z
published: 2026-02-13T13:51:19Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting your Development Environment Setup

This guide outlines solutions to common issues encountered during Rocket.Chat development setup. If your problem persists, further investigation may be required to identify the root cause.

## General troubleshooting

****Resolve a missing babel-runtime npm Package****

If you see an error similar to the following:

```node-repl
(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:

```bash
meteor npm install --save babel-runtime
```

****Resolve slower JavaScript implementation of**`bcrypt`**

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

```node-repl
(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:

```bash
meteor npm install --save bcrypt
```

****Python version not supported by**`node-gyp`**

If you encounter an error similar to the following:

```node-repl
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:

```bash
meteor npm config set python python2.7
```

Then rebuild the project:

```bash
meteor npm install --save bcrypt
```

Verify the installation by confirming output similar to the following:

```node-repl
> 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
```

**`libcuda.so.1`**is not a symbolic link****

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:

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

If the output shows this:

```bash
-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:

```bash
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:

```bash
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:

```bash
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:

```bash
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):

```bash
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:

```bash
yarn cache clean
```
7. Install dependencies and build the project:

```bash
yarn
yarn dsv
```

## Windows troubleshooting

**`exit 139`**segmentation fault in WSL****

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:

```matlab
notepad %UserProfile%\.wslconfig
```

1. You can replace `notepad` with `code` to use Visual Studio Code.
2. If the file does not exist, create it.
3. Add or update the following configuration:

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

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

```powershell
wsl --shutdown
```

Then launch your WSL distribution again.

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

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

1. Clean the project and rebuild:

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

> [!WARNING]
> If the error persists, try allocating at least 8GB of memory to WSL.

## MacOS troubleshooting

**`permission denied`**error when running yarn on macOS****

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

Confirm the error resembles:

```makefile
EACCES: permission denied
```

Run the following commands to restore ownership and write access:

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

These commands assign ownership of the `~/.yarn` directory to your user and ensure it is writable.

****Fixing**`fibers`**build failure on Apple Silicon (M1/M2/M3)****

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

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

this usually indicates that the module was not compiled correctly for the Apple Silicon architecture.

Follow the steps below to rebuild the module.

1. Install `node-gyp` globally:

```bash
npm install node-gyp --global
```

> [!NOTE]
> `node-gyp` introduced breaking changes in v10.0.0 and supports Node.js `^16.14.0 || &gt;=18.0.0`. If you encounter Node version compatibility issues, install `node-gyp@9.4.1` or earlier.
> 
> See the [release notes](https://github.com/nodejs/node-gyp/releases) for more details.

1. Rebuild `fibers` for the ARM64 architecture:

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

> [!NOTE]
> 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.

1. Copy the compiled binary to the expected location:

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

1. Replace the existing module inside Meteor:

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

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

****Fixing**`bcrypt`**architecture mismatch on Apple Silicon****

If you encounter an error similar to the following:

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

it indicates that the installed `bcrypt` binary was compiled for the **amd64 (x86_64)** architecture instead of **arm64**, which is required for Apple Silicon devices.

Rebuild the module using the steps below:

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

```bash
cd node_modules/bcrypt
make
```

This compiles the module for your system’s architecture.

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

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

****Fixing**`yarn dsv`**failure caused by the**`sharp`**module (Apple Silicon)****

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:

```css
softwareupdate --install-rosetta
```

1. Remove the existing Meteor installation:

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

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

1. Reinstall Meteor using x86_64 architecture:

```bash
arch -x86_64 npm install -g meteor
```

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

1. Rebuild the project:

```bash
yarn && yarn build && yarn dsv
```

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

```arduino
http://localhost:3000
```

**`bcrypt`**fails with an “incompatible architecture” error after running**`yarn dsv `**(Apple Silicon)****

If you encounter an error similar to the following:

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

this indicates an architecture mismatch. Meteor is attempting to use the `x86_64` architecture while your system is running on `arm64`.

This issue occurs on Mac systems with Apple Silicon chips. Although Meteor supports the `arm64` architecture, it may default to `x86_64` if the existing installation was created before ARM support was introduced.

**Resolution:**

Remove the current Meteor installation and reinstall it using the commands below:

```bash
rm -rf ~/.meteor
npx meteor
```

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