# Troubleshooting (/docs/ship/troubleshooting)



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

## Installs [#installs]

### `401 Unauthorized` / `403 Forbidden` from npm.appbrew\.tech [#401-unauthorized--403-forbidden-from-npmappbrewtech]

The committed registry token was rotated. See [Registry access](/docs/ship/registry-access). Public packages keep installing fine while `@gauntlet/*` fails.

### `ERR_PNPM_NO_MATCHING_VERSION` on a `@gauntlet` package [#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](/docs/ship/upgrading)).

### Wrong Node or pnpm version errors [#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](/docs/start/prerequisites)). If mise prompts about an untrusted config, run `mise trust`.

## Android [#android]

### App crashes on launch with `couldn't find DSO to load` / missing `.so` library [#app-crashes-on-launch-with-couldnt-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 [#gradle-build-fails-after-an-upgrade]

Stop stale daemons and rebuild clean:

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

## iOS [#ios]

### Pod install fails or the build breaks after an upgrade [#pod-install-fails-or-the-build-breaks-after-an-upgrade]

```bash
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](/docs/start/prerequisites).

### `xcodebuild` cannot find a simulator [#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 [#the-js-bundle]

### Changes don't show up / stale code runs [#changes-dont-show-up--stale-code-runs]

Reset the bundler cache:

```bash
pnpm start --reset-cache
```

### Red screen: block renders nothing or crashes [#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](/docs/build/testing) and null-check `useBlockSettings` results.

## Still stuck? [#still-stuck]

[Contact Appbrew](/docs/start/getting-help) with the exact command, the full error output, and your platform — that combination usually gets a same-day answer.