Troubleshooting

The failures below account for most first-week problems. Each entry leads with the error you will actually see.

Installs

401 Unauthorized / 403 Forbidden from npm.appbrew.tech

The committed registry token was rotated. See Registry access. Public packages keep installing fine while @gauntlet/* fails.

ERR_PNPM_NO_MATCHING_VERSION on a @gauntlet package

Your package.json set is mixed — one entry points at a version that doesn't exist or doesn't match the rest. Make every @gauntlet/* pin identical (Upgrading).

Wrong Node or pnpm version errors

Another version manager (nvm, asdf, corepack) is shadowing mise. Run mise install inside the repo and check which node resolves through mise (Prerequisites). If mise prompts about an untrusted config, run mise trust.

Android

App crashes on launch with couldn't find DSO to load / missing .so library

node_modules was installed without the hoisted layout — usually node-linker=hoisted was removed from .npmrc, or the install ran with npm/yarn instead of pnpm. Restore the setting, delete node_modules, reinstall with pnpm, rebuild.

Gradle build fails after an upgrade

Stop stale daemons and rebuild clean:

cd android && ./gradlew --stop && cd ..
pnpm run-android

iOS

Pod install fails or the build breaks after an upgrade

pnpm clean-ios
pnpm run-ios

This resets Pods and reinstalls them against the current dependency set. Xcode version drift is the other usual suspect — check Prerequisites.

xcodebuild cannot find a simulator

Open Xcode once after install/update to accept licenses and download a simulator runtime, then boot a simulator from Xcode before pnpm run-ios.

The JS bundle

Changes don't show up / stale code runs

Reset the bundler cache:

pnpm start --reset-cache

Red screen: block renders nothing or crashes

A missing registry entry logs <componentId> is missing in block registry and renders nothing — check register-blocks.ts. A crash inside your block usually means unguarded config access. Fail soft and null-check useBlockSettings results.

Still stuck?

Contact Appbrew with the exact command, the full error output, and your platform — that combination usually gets a same-day answer.