Troubleshooting — Voidhash Docs

Find your symptom below; each section lists causes in the order to check them. Set debug: true and an onDiagnostic handler while you investigate: most problems show up there first. See Diagnostics.

FLOW_RENDERER_MISSING

The build doesn't include the paywall renderer. The published packages don't ship it yet, so follow Add the paywall renderer and check:

node_modules/@voidhash/ios-ui contains Artifacts/VoidhashUIEngine.xcframework, and node_modules/@voidhash/android/ui/src/main/jniLibs contains libvoidhash_ui.so for each ABI. Reinstalling dependencies removes them.
In Expo, the plugin is registered as ["@voidhash/react-native", { "renderer": true }], not the bare string. In a bare app, the Podfile has the VoidhashUI pod and android/gradle.properties has Voidhash_renderer=true.
You ran npx expo prebuild and rebuilt the native app. A JavaScript reload or an over-the-air update doesn't add native code.

The paywall doesn't appear

Check the failed result's error.code:

FLOW_NOT_ASSIGNED: nothing is shown at the location. Check the slug you pass to presentFlow, that the location isn't archived, and that a paywall is deployed and shown there. See Paywall locations. If it is, the deployed build may need a newer SDK.
FLOW_UNAVAILABLE: the device has never loaded this location and is offline, or the paywall wasn't ready to show within 15 seconds.
FLOW_UNSUPPORTED_PACKAGE: update the SDK.
FLOW_PRESENTATION_FAILED: present from a screen that is mounted and visible.

A paywall you just deployed can take up to about an hour to replace a cached one on a device that showed the location before. Reinstall the app to test a deploy right away.

Products are empty

useProducts() returns undefined for a product, or a paywall shows no prices. The SDK reports each missing product through onDiagnostic as PRODUCT_NOT_FOUND, with the store's reason.

In a debug build with dev: true, check that you use the test key (vh_pk_test_...) and that Enable simulated purchases is on in Settings → General.
Otherwise, check that the App Store or Google Play is connected and the product is mapped to its store product ID. See Products and perks.
Check the product in the store: on the App Store, the Paid Applications Agreement is active and the product is ready to submit; on Google Play, the app is published to a testing track and the product is active.
Test on a real device signed in to a sandbox or license tester account; see Test purchases (Help center).

A purchase doesn't unlock the perk

Check the purchase result. deferred means the receipt is still queued for Voidhash; access arrives once it's accepted. pending waits for approval.
Check that the product unlocks the perk you check, by slug, in Products → Products.
Watch onDiagnostic for TRANSACTION_REJECTED: Voidhash refused the receipt, usually because the store isn't connected for this bundle ID or package name.
Check the key: a TestFlight or Play test build on the test key doesn't see production perks, and with the store-sandbox-unlocks-production setting off, sandbox purchases don't unlock production apps. See Environments.
In observer mode, check that you report the purchase with reportTransaction.

Expo Go isn't supported

The SDK ships native modules, which Expo Go can't load: the app still runs, but initialization fails with FAILED_TO_INITIALIZE_VOIDHASH_CLIENT. Use a development build (npx expo run:ios, npx expo run:android or EAS). The same error appears when an over-the-air update ships the SDK's JavaScript to a binary built without it; rebuild the binary.

Native build fails

iOS pod install can't find VoidhashCore: in a bare app, add the Podfile lines from the quickstart. In Expo, the plugin needs a use_expo_modules! or use_native_modules! line in the Podfile.
Errors mentioning Nitro: every Nitro module in the app must use the same 0.37.x version.
Android billing errors at runtime: another billing library in the app still uses APIs removed in Google Play Billing 8. Upgrade it. The SDK needs compileSdkVersion 35.
effect errors: install exactly effect@4.0.7.

Sandbox purchases

TestFlight and Play test-track builds use the production key; their purchases are recorded in the sandbox environment and appear under Sandbox in Studio.
The App Store sandbox renews subscriptions on an accelerated schedule; the renewals arrive as regular renewals.
Simulated purchases from development mode appear under Test. Move them through renewals and refunds with voidhash sandbox; see Development mode.

Events don't show up

Check analytics consent: with "denied" or "pending", nothing is recorded and ANALYTICS_CONSENT_DENIED is reported once.
Check the environment in Studio: debug builds on the test key send test events, shown under Test.
Check Settings → Events: a turned-off built-in event or a blocked custom event isn't stored.
Events are sent every 5 seconds or 20 events. Call flush() and check pending and lastError.
AUTHENTICATION_FAILED in onDiagnostic means the publishable key was rejected.

See Check your data for what Studio received.

Call identify() and signOut() only after your auth library has restored the session. Signing out while the session is still loading discards the identity that holds the person's purchases. signOut() does nothing for an anonymous person; reset() replaces their identity and leaves their purchases behind.
PERSON_WRITE_REJECTED after identify() means the anonymous ID already belonged to another identified user, so its purchases weren't merged. A Restore button moves them according to the project's paid access sharing setting.

Next steps