Setup troubleshooting

A few reported setup hiccups and how to fix them.

#Node.js version requirements

Jazz requires Node.js v20 or later due to native module dependencies.
Check your version:

node -v

If you’re on Node 18 or earlier, upgrade via nvm:

nvm install 20
nvm use 20

#Required TypeScript Configuration

In order to build successfully with TypeScript, you must ensure that you have the following options configured (either in your tsconfig.json or using the command line):

• skipLibCheck must be true
• exactOptionalPropertyTypes must be false

#npx jazz-run: command not found

If, when running:

npx jazz-run sync

you encounter:

sh: jazz-run: command not found

This is often due to an npx cache quirk. (For most apps using Jazz)

1. Clear your npx cache:

npx clear-npx-cache

2. Rerun the command:

npx jazz-run sync

#Node 18 workaround (rebuilding the native module)

If you can’t upgrade to Node 20+, you can rebuild the native better-sqlite3 module for your architecture.

1. Install jazz-run locally in your project:

pnpm add -D jazz-run

2. Find the installed version of better-sqlite3 inside node_modules. It should look like this:

./node_modules/.pnpm/better-sqlite3{version}/node_modules/better-sqlite3

Replace {version} with your installed version and run:

# Navigate to the installed module and rebuild
pushd ./node_modules/.pnpm/better-sqlite3{version}/node_modules/better-sqlite3
&& pnpm install
&& popd

If you get ModuleNotFoundError: No module named 'distutils': Linux:

pip install --upgrade setuptools

macOS:

brew install python-setuptools

Workaround originally shared by @aheissenberger on Jun 24, 2025.

#Still having trouble?

If none of the above fixes work:

Make sure dependencies installed without errors (pnpm install).

Double-check your node -v output matches the required version.

Open an issue on GitHub with:

• Your OS and version

• Node.js version

• Steps you ran and full error output

We're always happy to help! If you're stuck, reachout via Discord