revenuecat-troubleshoot

revenuecat-troubleshoot: diagnose RevenueCat integration problems

Use this skill when the user reports a RevenueCat behavior that does not match expectations: empty offerings, missing products, an entitlement that does not unlock after a successful purchase, a paywall that fails to render, or sandbox transactions that never reach the dashboard.

This skill combines two angles:

1. Code-side diagnosis — turn on debug logging, walk a universal checklist, drop into platform specifics.
2. Dashboard inspection — use the RevenueCat MCP server or the rc CLI (see the revenuecat-cli skill) to read the project, apps, products, entitlements, offerings, and webhooks, and offer fixes.

Work them in order. Most reports resolve before you reach the platform specifics.

1. Detect the platform

Inspect the working directory and pick the first match, from top to bottom:

1. React Native: package.json has a react-native-purchases entry, or react-native as a dependency → read platforms/react-native.md. If expo is also a dependency, note it as an Expo project.
2. Flutter: pubspec.yaml exists at the project root → read platforms/flutter.md.
3. Kotlin Multiplatform: build.gradle.kts contains a kotlin { … } multiplatform source sets block, or depends on com.revenuecat.purchases:purchases-kmp* → read platforms/kmp.md.
4. Android (native): build.gradle(.kts) applies com.android.application (and is not KMP) → read platforms/android.md.
5. iOS (native): Package.swift, *.xcodeproj, *.xcworkspace, or Podfile at the project root → read platforms/ios.md.

If several match (e.g. an ios/ folder inside a Flutter project), pick the outermost project, the one that owns the build. If still ambiguous, ask the user which platform the bug reproduces on.

2. Universal code-side checklist

Walk these nine items in order. Most reports are resolved by steps 1 through 5.

1. Turn on debug logging and reproduce. The SDK narrates what it is doing. Roughly 80% of reports are diagnosable from the log output alone. Each platform file shows how to set logLevel to debug.
2. Verify the API key platform matches the app. iOS apps must use an appl_… public SDK key. Android apps must use goog_… (or amzn_… for Amazon). A mismatched key produces an authentication error on the first network call. On iOS this surfaces as an INVALID_CREDENTIALS error code. On Android it surfaces as PurchasesErrorCode.InvalidCredentialsError. Use the list-app-public-api-keys RevenueCat MCP tool to list the API keys for the project.
3. Verify the bundle ID / package name matches the one set up in the RevenueCat project. List the apps using the list-apps RevenueCat MCP tool. The bundle_id (iOS / App Store) or package_name (Android / Play Store / Amazon Appstore) registered there must match the built app exactly, including capitalization. A mismatch causes offerings to come back empty because the app is not recognized.
4. Verify offerings in the RevenueCat project. List the project's offerings using the list-offerings RevenueCat MCP tool, passing the parameter expand=items.package.product. The offering marked with is_current: true must have at least one package attached, and each package must reference a store product. An offering with zero packages returns an empty availablePackages list even though getOfferings succeeds.
5. Verify store products are live. Products must be in "Ready to Submit" on App Store Connect or "Active" on Google Play Console. A product in a draft state will not be returned by the store, even in sandbox. If the SDK logs show offerings arriving from RevenueCat but products failing to resolve, this is almost always the cause. Use the get-product-store-state RevenueCat MCP tool to understand the state of product in App Store Connect or Google Play Console (field store_status). To fix or change the store state (not just read it), follow the revenuecat-store-state skill.
6. Verify the testing account. iOS: the device must be signed into a Sandbox Apple ID under Settings → App Store → Sandbox Account (set on iOS 14+ after the first sandbox prompt). Android: the tester's Gmail must be added to Google Play Console → Setup → License testing, and the app must be installed via the Internal Testing opt-in link, not sideloaded.
7. Verify the network. Corporate VPNs, captive portals, and some DNS filters silently block the RevenueCat API or the store APIs. Try a different network before digging deeper.
8. Verify the appUserID. If logIn(appUserID) was called with an ID that does not match what the user expects, entitlements appear missing because they are attached to a different RC user. Print Purchases.shared.appUserID (iOS) / Purchases.sharedInstance.appUserID (Android) and confirm it matches.
9. Reset and retry. Uninstall the app, re-sign into the sandbox / tester account, reinstall from the correct channel, relaunch.