# 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. |
| `Yodl tokenlist[2].decimals must be a non-negative integer`, or a similar error when the app starts | An entry of your [`tokenlist`](/sdk/react-native/api#tokenlist) isn't a valid token. The message names the entry and the field. `createYodlSdk` refuses the list rather than send one the hosted UI would reject. |
| A token in your `tokenlist` never appears | Only tokens the user holds are shown. Beyond that, the token is on a chain Yodl doesn't read, or its `address` holds no token contract on that chain. Check the `chainId` and the address. |
| A token in your `tokenlist` shows a balance but can't be used to pay | It has neither `extensions.coinGeckoId` nor `extensions.peggedTo: 'USD'`, so it is valued at zero and never covers a payment. Add one of them. |
| Changing `tokenlist` has no effect | The list is read once, by `createYodlSdk`, and a mounted component keeps the list its page loaded with. Create a new SDK with the whole new list and remount the component. |
| A payment from a listed token fails when the wallet is asked to switch chain | The token is on a chain outside `supportedChainIds`, so the SDK refuses the switch. List only tokens on chains in `supportedChainIds`. |

## 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. A page that failed to load reaches `onError` as a [`YodlWebViewError`](/sdk/react-native/api#errors); pair it with 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.