Skip to main content

​
Troubleshoot React Native and Expo

​
Flags always use the fallback

Inspect useFlags() first:
Check that:
  • the app received the intended pub_ key;
  • the flag and all advanced dependencies are client-visible;
  • a stable targetingKey is present;
  • targeting attributes are on the environment allow-list; and
  • the device can reach https://superflag.sh.
Do not log the complete key or evaluation context.

​
AsyncStorage is unavailable

For bare React Native, install pods after adding the dependency. The SDK contains missing or failing native storage operations so startup should fail closed to fallbacks rather than crash. A missing peer still means persistent caching is unavailable and must be fixed before release.

​
An OTA update changed flag behavior

JavaScript-only provider, hook, key, targeting, and flag-consumer changes can be delivered through an Expo OTA update when they remain compatible with the installed native runtime. Adding or changing a native dependency still requires a compatible native build.

​
Foreground refresh is not running

The default guarded AppState adapter refreshes when the app moves from background or inactive to active. If you pass appState={null}, that behavior is disabled. Reconnect refresh requires an injected network adapter.

​
Production verification

Test the same package graph in a production-style Expo bundle before release. Superflag’s package gate builds a clean Expo consumer with Metro and compiles Hermes bytecode; your application should still test its own environment values, OTA runtime compatibility, startup path, and fallback UI.