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:

npm view @rollbird/cli version --registry=https://registry.npmjs.org

For an SDK error, check the SDK package instead:

npm view @rollbird/react-native version --registry=https://registry.npmjs.org

Then retry installation against that registry:

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:

Not logged in.

Run the suggested interactive flow:

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:

No rollbird.json found in this directory.

Run commands from the app root. If the project has not been linked yet, run:

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:

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:

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:

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:

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:

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:

npm uninstall expo-updates

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:

npx rollbird init

For Expo, apply the plugin afterward:

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 <platform>, 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:

--rollout must be an integer between 1 and 100.

Platform accepts exactly ios or android. Other values report Invalid --platform "<value>"; expected "ios" or "android".

Use command help to inspect the exact supported flags:

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:

Release 17 not found on the preview channel.

Check the channel and recent history with:

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.