# Troubleshooting

| Symptom | Cause and fix |
| --- | --- |
| `Can't find variable: BigInt` | Hermes is disabled. Re-enable it or add a `BigInt` polyfill — see [requirements](/sdk/react-native#requirements). |
| App crashes or shows a blank screen in Expo Go | Native modules aren't available in Expo Go. Use a [development build](https://docs.expo.dev/develop/development-builds/introduction/). |
| `Yodl components must be rendered inside <YodlProvider>` | A component is mounted outside the provider. Wrap it in `<YodlProvider>`. |
| Payment screen renders blank | `qrData` isn't a Yodl payment QR. Guard with `isPaymentQr(qrData)` before rendering `<YodlPayment>`. |
| `webview-action providers are not supported yet` | The scanned QR maps to a provider whose hosted webview flow isn't supported yet. Catch it via `onError` or an error boundary and prompt a retry. |
| The overlay lifts after ~8 seconds onto a blank or unthemed page | The reveal ceiling fired because the hosted UI never reported readiness — see [the two ceilings](#the-two-ceilings) below. |
| Nothing covers the WebView while it loads | `renderLoading` returned `null`, which suppresses the overlay by design. Return an element, or omit the prop for the default indicator. See [loading and readiness](/sdk/react-native/api#loading-and-readiness). |
| Theme silently doesn't apply | An invalid `theme` or `themeMode` falls back to stock Yodl rather than crashing, and logs the reason when `__DEV__` is true. Check the dev console. |

## The two ceilings

The loading overlay is meant to lift on a signal from the hosted UI: the page reports it has painted, and the SDK reveals it. Two independent timers exist only so that never becomes *never*.

| Ceiling | Where | What it means when it fires |
| --- | --- | --- |
| 6 s | The hosted UI | The page is up but something inside it is slow. It reports readiness anyway, so the reveal still carries your theme and the SDK's capability handshake. You will not notice this one. |
| 8 s | The SDK | Nothing at all came back. The SDK reveals and fires `onReady` regardless. |

The order matters and is deliberate: the page always gives up first, so any page that exists gets the full themed handshake. Reaching the SDK's 8 seconds means the hosted document never ran — an unreachable `yodlUiBaseUrl`, no network, or a build old enough not to report readiness. In the last case the theme is never delivered either, so the page appears in stock Yodl colours rather than yours.

The ceiling reveals. It does not report an error, and there is no retry — surface network failures through `onError` and your own connectivity handling.

## The two blank-screen cases

They look identical and have different causes, so check in this order:

1. **Running in Expo Go** — see [requirements](/sdk/react-native#requirements). No JS change fixes this.
2. **A valid dev build** — then `qrData` isn't a supported payment QR. `<YodlPayment>` deliberately renders nothing rather than erroring, which is why the guard in the [quickstart](/sdk/react-native/quickstart) matters.

Still stuck? Payment-side issues that aren't in this table are usually visible in `onPaymentDetails` — log the whole object, including `raw`, before filing anything.