> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newly.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting
> Common subscription issues and how to fix them
## "No subscription plans available"
This usually means one of:
* **Entitlement mismatch** — your app expects an entitlement that doesn't match what's in RevenueCat. Newly uses "pro" as the entitlement name. Check your RevenueCat dashboard.
* **Incomplete catalog** — products, offerings, or packages weren't created. Check your RevenueCat dashboard for a complete catalog.
* **Missing API keys** — your app doesn't have the right SDK keys configured.
Ask the AI agent to run a diagnosis — it has a built-in tool that validates your `app.json` configuration against your RevenueCat dashboard and reports specific issues.
## "RevenueCat session expired"
RevenueCat OAuth tokens expire after approximately 1 hour. The system auto-refreshes them in most cases, but occasionally you may need to reconnect.
**Fix:** Re-run the RevenueCat connection flow. Ask the AI to "reconnect RevenueCat" or use the settings panel.
## Purchases work in dev but not production
Getting production purchases to work is one of the hardest parts of launching a mobile app. Even experienced developers get stuck here. Be patient — this process involves multiple external systems (Apple, Google, RevenueCat) that all need to be correctly configured and fully propagated.
Production purchases failing while dev/test purchases work is **the most common subscription issue**. Work through every step below in order.
### Step 1: Accept the Paid Applications Agreement (Apple)
This is the **number one cause** of production purchase failures. Without this, nothing else will work.
1. Go to [App Store Connect Business](https://appstoreconnect.apple.com/business)
2. Under **Paid Apps**, look for a **"Review and Accept"** button or a yellow/red banner
3. **Accept the agreement** if prompted
4. **Complete all required forms**: tax information, bank account details, and contact information
If any of these forms are incomplete, Apple will reject all in-app purchase operations — including RevenueCat's ability to validate your IAP keys. Your RevenueCat dashboard may show key validation errors until this is fully resolved.
### Step 2: Wait for Apple propagation
If your app was recently created in App Store Connect, Apple may need **up to 24–48 hours** to fully propagate your app's bundle ID and subscription configuration. During this time:
* IAP key validation in RevenueCat may fail
* Products may not appear in the SDK
* Receipt validation may return errors
There is no way to speed this up. If your app was created in the last 48 hours and everything else looks correct, wait and retry.
### Step 3: Verify your Apple credentials
Ensure the following are configured in your Newly dashboard:
| Credential | What it does | How to check |
| --------------------- | ------------------------------------------------- | ----------------------------------- |
| **ASC API Key** (.p8) | Creates and manages products in App Store Connect | Newly dashboard → Apple credentials |
| **IAP Key** (.p8) | Lets RevenueCat validate purchase receipts | Newly dashboard → Apple credentials |
These are typically auto-provisioned when you connect your Apple Developer account. If they show errors, try disconnecting and reconnecting your Apple credentials.
### Step 4: Check your RevenueCat configuration
Open your [RevenueCat dashboard](https://app.revenuecat.com) and verify:
* Your app has an **App Store** app with the correct bundle ID
* The IAP key status shows as **valid** (not "invalid" or "pending")
* Your offering is set as **Current**
* Products in the offering have **pricing configured**
### Step 5: Use RevenueCat's troubleshooting guide
RevenueCat has a detailed guide for diagnosing offering and product issues:
**[RevenueCat Offerings Troubleshooting Guide](https://www.revenuecat.com/docs/offerings/troubleshooting-offerings)**
This guide covers SDK-level debugging, verifying your product configuration, and common pitfalls. It requires some technical depth — take your time with it.
### Still stuck?
Production purchase issues can be genuinely difficult to resolve, especially if you are new to mobile app development. If you have worked through all the steps above and purchases still are not working:
* **Ask the AI agent** to run a diagnosis — it validates your full configuration and identifies specific mismatches
* **Use the in-app support widget** to reach out to support without leaving your project
* **Email us** at [support@newly.app](mailto:support@newly.app) with your project name and a description of the error
* **Need hands-on help?** Our [Consulting plan](https://newly.app/pricing?tab=plans) includes dedicated support where we handle complex setup like production purchases for you
Production purchases involve Apple/Google account setup, RevenueCat configuration, and app-level code all working together. A failure in any one of these layers can cause purchases to silently fail. Do not assume the problem is in your app code — it is almost always an account or configuration issue.
## "Missing Metadata" in RevenueCat
You may see a **"Missing Metadata"** warning on your product in the RevenueCat dashboard:
This means the subscription product was created in App Store Connect, but Apple still needs additional metadata before it can go live. Newly auto-creates the products, but some metadata must be completed manually in App Store Connect for now.
**Fix:** Go to [App Store Connect](https://appstoreconnect.apple.com) and complete the missing metadata:
1. Navigate to **My Apps** → your app → **Subscriptions**
2. Select your subscription group (usually "NSubscriptions")
3. For each product, check that the following are all set:
* **Localization** — display name and description in at least one language (English)
* **Pricing** — at least one price set for a territory
* **Review screenshot** — an image for Apple's review team
Once all metadata is filled in, the product status in App Store Connect should change from "Missing Metadata" to **"Ready to Submit"**, and the warning in your RevenueCat dashboard should disappear.
For a step-by-step checklist, see [RevenueCat's offerings troubleshooting guide](https://www.revenuecat.com/docs/offerings/troubleshooting-offerings) — scroll down to the **App Store** section and verify each requirement. You can also refer to [Apple's in-app purchase status reference](https://developer.apple.com/help/app-store-connect/reference/in-app-purchases-and-subscriptions/in-app-purchase-statuses) for a full list of what Apple requires.
## Paywall shows "Premium Feature 1, 2, 3"
The AI agent should auto-generate realistic feature names based on your app's functionality. If you see generic placeholder text:
**Fix:** Ask the AI to "update the paywall features" or "make the paywall match my app's features". It will analyze your app and suggest relevant premium feature descriptions.
## Purchases not syncing across devices
This happens when your app doesn't have authentication. Without a user ID, RevenueCat can't link purchases across devices.
**Fix:** Add authentication to your app. Ask the AI to "set up auth" — once auth exists, the subscription system will automatically start syncing purchases via user ID.
See [Authentication & Subscriptions](/subscriptions/authentication) for more details.
## "Invalid API key" error in Expo Go
RevenueCat purchases do not work in standard Expo Go. You need a custom dev build.
**Fix:** Run `npx expo prebuild` and build for your device. See [Testing Purchases](/subscriptions/testing) for details.
## Connection issues after setup
If the RevenueCat integration seems broken after initial setup:
1. Check if your OAuth session expired (re-run connection flow)
2. Verify products exist in your RevenueCat dashboard
3. Confirm API keys are present in your `app.json` (see [Technical Details](/subscriptions/technical-details))
4. Ask the AI to diagnose the issue — it can validate the full configuration