# Troubleshooting Start with the exact CLI message. Rollbird errors are intended to tell you whether the fix belongs in authentication, project configuration, native compatibility, the release command, or the account plan. ## npm install returns 404 Both `@rollbird/cli` and `@rollbird/react-native` are public npm packages. If installation returns `404` or package-not-found, first confirm npm can see the CLI on the public registry: ```bash npm view @rollbird/cli version --registry=https://registry.npmjs.org ``` For an SDK error, check the SDK package instead: ```bash npm view @rollbird/react-native version --registry=https://registry.npmjs.org ``` Then retry installation against that registry: ```bash npm install --save-dev @rollbird/cli --registry=https://registry.npmjs.org ``` If `npm view` succeeds but installation still fails, inspect the app's `.npmrc`, the user-level `~/.npmrc`, and any corporate registry proxy for an override of the `@rollbird` scope. Do not substitute an unrelated package with a similar name. ## Not logged in Message: ```text Not logged in. ``` Run the suggested interactive flow: ```bash npx rollbird login ``` In CI, set `ROLLBIRD_TOKEN` instead. A device code that expires reports `Device code expired. Run rollbird login again.`; start a new login flow rather than reusing the code. ## Project configuration is missing Message: ```text No rollbird.json found in this directory. ``` Run commands from the app root. If the project has not been linked yet, run: ```bash npx rollbird init ``` Commit `rollbird.json` after setup. It contains public project configuration, not the API token or private signing key. ## React Native project is not detected Message: ```text No React Native project detected in this directory. ``` Confirm the current directory has the app's `package.json` and that `react-native` is a dependency. For a bare project, Rollbird also requires an `ios/` or `android/` directory and can report: ```text Neither an ios/ nor android/ directory was found. ``` For Expo CNG, keep an Expo config file at the project root so `init` can register or describe the config plugin. ## Native app identifiers are not detected When Android detection fails, the CLI reports `Android application id could not be detected.` Supply it explicitly: ```bash npx rollbird init --android-app-id com.example.app ``` When iOS detection fails, it reports `iOS bundle identifier could not be detected.` Supply that value explicitly: ```bash npx rollbird init --ios-bundle-id com.example.app ``` Both identifiers may be passed in the same `init` invocation when needed. ## Expo Updates conflicts with Rollbird Message: ```text expo-updates is installed. It and Rollbird both control the app's update process, so an app with both updates unpredictably or crashes. ``` Choose one update system. To use Rollbird, stop using EAS Update, remove `expo-updates`, and rerun initialization: ```bash npm uninstall expo-updates ``` ```bash npx rollbird init ``` ## Fingerprint is missing or stale An Expo release can stop with a message beginning `rollbird.json has no stored fingerprint`. A bare release can warn that native config has no fingerprint or that native code changed since initialization. Refresh the stored and embedded configuration: ```bash npx rollbird init ``` For Expo, apply the plugin afterward: ```bash npx expo prebuild ``` Then rebuild and redistribute the native app. Publishing another JavaScript bundle cannot retrofit a missing or old fingerprint into an installed binary. ## Hermes compiler is missing The error starts with `Hermes is enabled for , but no Hermes compiler was found in this project`. Install the app's dependencies from its lockfile and confirm the app's own React Native package includes the compiler. Rollbird deliberately does not use a globally installed compiler because Hermes bytecode must match the app's native runtime. If the Expo app intentionally uses JavaScriptCore, set `"jsEngine": "jsc"` in its Expo config, rebuild, and rerun the release. Do not change engines only to bypass a missing dependency install. ## Release flags are rejected Rollout accepts an integer from 1 through 100. Invalid input reports: ```text --rollout must be an integer between 1 and 100. ``` Platform accepts exactly `ios` or `android`. Other values report `Invalid --platform ""; expected "ios" or "android".` Use command help to inspect the exact supported flags: ```bash npx rollbird release --help ``` ## The device does not receive a release Check these conditions in order: 1. The installed binary's channel matches the release channel. 2. The release contains an artifact for the device platform. 3. The binary and release use compatible fingerprint or app-version values. 4. The rollout includes that device. 5. The release is active rather than paused or disabled. 6. The device can reach `https://ota.rollbird.dev`. The CLI warns when publishing to a channel different from the channel stored in `rollbird.json`. That publish succeeds because another binary may use the target channel; the current binary will not switch channels dynamically. A normal update becomes active on the next launch. Close and relaunch the app after the download finishes. A forced update reloads automatically unless the wrapper sets `reloadOnForceUpdate: false`. ## Rollback cannot find a release An explicit number that is absent from the selected channel reports: ```text Release 17 not found on the preview channel. ``` Check the channel and recent history with: ```bash npx rollbird status ``` With no number, rollback targets the latest active release. If none exists, the CLI currently reports `No active production release to roll back` even when another channel was selected. This wording is a known CLI limitation. Rollback itself is never blocked by quota, storage, or plan status. When no earlier OTA release remains, the app serves its embedded bundle. ## CI authentication or scope fails Confirm the secret is named exactly `ROLLBIRD_TOKEN`, is available to that job, and contains the token value rather than its display name. Release jobs need `release:write`; status and release reads need `release:read`. The reference CI token has both. A project-bound token must match the `projectId` in `rollbird.json`. Create a new correctly bound token instead of copying configuration from another app. Use the exit code to classify the failure: `3` is authentication, `4` is a plan restriction, and `5` is network, storage, or server failure. ## Current verification limits The documentation build, package tests, CLI help, static links, and responsive pages are verified in the Rollbird repository. Public package installation and a real end-to-end device update require the packages to be published plus a consumer app, native toolchains, signing credentials, and a device. Where a guide depends on those prerequisites, it says so instead of presenting sample output as a live device result.