Troubleshooting
Things break. When they do, this page is the first stop. It's a running list of the most common things that go wrong, in rough order of how often we see them, and exactly how to fix each one.
If your issue isn't here, jump to the bottom. There's a "still stuck" section with how to reach us.
The preview is blank on my phone
Several possible causes, roughly in order:
- A run is still in progress. The phone preview deliberately pauses while the agent works, so it never shows you a half-written app. Let the run finish; the finished version publishes automatically.
- The device or Expo Go version is incompatible. Hosted iPhone preview is currently unavailable. On Android, install Expo Go for SDK 54; updating to the latest store version can make compatibility worse. See device compatibility.
- JavaScript error on first render. Shake your phone for the dev menu and read the error. If the app crashed outright, Appsanic usually catches it and shows it beside the preview panel - tap Send to chat to hand the agent the real stack trace.
- The session went stale. Close Expo Go and scan the QR again.
Your phone and your computer do not need to be on the same network - the session is served over the internet, so a different Wi-Fi or a mobile connection is fine.
If none of that works, send another message in chat. The next completed run republishes the session from scratch, which clears almost everything transient.
"Native module X is not linked" or "Cannot find module react-native-xxx"
Translation: the agent added a library that needs special "native" code on the phone, but Expo Go doesn't include that specific library, so it can't run it.
Fix: tell the agent what the error says and ask it to use a supported approach instead:
"Expo Go says react-native-xxx isn't linked. Rebuild that feature using something Expo Go can run."
The agent builds against a fixed set of libraries that Expo Go carries, so a message like this is nearly always a stray import it can replace. If the feature genuinely needs native code that Expo Go does not include (in-app purchases, interactive maps, real ads), the route is a real build: use Publish and test through TestFlight or the Play internal track. See Publishing to the app stores.
Log-in doesn't work
- Check that you verified your email. If not, check spam; re-send from the log-in screen.
- Check that your Supabase project is live. Sometimes Supabase pauses free-tier projects for inactivity. Unpause from the Supabase dashboard.
- Reset your password from the log-in screen if you're unsure.
- Log out of everything and log back in: clear cookies, restart Expo Go, try again.
If it's consistent across devices, check the Supabase dashboard > Logs > Auth for the specific error.
Stripe checkout doesn't charge me in test mode
You're probably using a live publishable key but a test secret key (or vice versa). They don't mix.
- Your project's Stripe connection is managed from its build under Connectors → Stripe. The publishable key remains visible; the secret key shows as dots. If you're unsure which mode you saved, enter a matched pair from the same mode again.
- Both should start with
pk_test_andsk_test_respectively (for test mode), or bothpk_live_andsk_live_(for production). - Click Test connection on the connector page after changing keys.
Also check your webhook secret matches the mode you're in.
Stripe webhook events aren't hitting my backend
- Is the webhook URL correct in the Stripe dashboard? It should point at your app's backend webhook endpoint.
- Is the webhook secret correct? Re-save it on the Stripe connector page (Dashboard > Connectors > Stripe), then run a build so the change takes effect.
- Is Stripe showing failures in the Events log? Stripe > Developers > Events. Failed webhooks show the error, usually a mismatched signature or a 4xx from your app.
Send a test webhook from the Stripe dashboard (Developers > Webhooks > your endpoint > Send test webhook) to verify the pipe is clean before assuming your business logic is broken. Webhook endpoint registration and signing-secret provisioning are manual security steps. Keep the secret only in the deployed payments backend's environment, never in chat or client code.
Push notifications aren't arriving
- Are you testing on a real device? Pushes don't fire in the simulator/emulator.
- Did the user grant permission? Check Settings > [Your app] > Notifications on the device.
- Do you have an Expo push token stored? Check your
push_tokenstable (or wherever the agent stored it). The token should start withExponentPushToken[. - Are the iOS push credentials uploaded to Expo? Expo dashboard > Credentials > iOS.
- Are the Android FCM credentials uploaded? Expo dashboard > Credentials > Android. The
google-services.jsonmust be current. - Sending pushes from your own server? The Expo Push connector validates build-time configuration only. Check that you deployed the generated send function and provisioned a separate runtime token in its secret manager. Receiving does not need the connector secret, but it still needs platform credentials, native setup, and a real-device development build.
If all of that checks out, send a test push from Expo's push tool with the token. That isolates whether the problem is delivery or your send-from-server logic.
The build stopped and asked me to connect a service
That's by design. When the agent needs a service that isn't connected yet - say, Stripe for a checkout screen - it stops, says why in one sentence, and shows a connect card in the chat.
- Click Connect on the card. The connectors modal opens at that provider, right there on the build page - you don't lose your place.
- Follow the setup guide and enter a least-privilege credential in the connector form. Connector OAuth is not currently available.
- The card detects the connection on its own and the build resumes automatically. If it hasn't noticed after a few seconds, click "I'm done - check now" on the card.
One thing that won't work: pasting the key into the chat. The agent refuses keys in chat and points you to the dashboard - chat history is not a safe place for secrets. See In-Chat Connect Cards for the full flow.
My export to GitHub fails
- Is Appsanic authorized for your GitHub account? Open the GitHub panel in the builder - if you're not connected, it shows a Connect GitHub button. You can also check GitHub > Settings > Applications > Authorized OAuth Apps.
- Do you have permission to create repos in the target org? If you chose an org, your GitHub role must allow creating repos.
- Is the repo name already taken? Pick a different name; GitHub rejects duplicates.
For orgs with strict audit rules, your org admin may need to approve Appsanic as an OAuth app before you can export there.
The App Store rejected my app
Most first rejections come from one of five reasons (see Publishing to the App Store):
- Crashes on launch → test on a real iPhone before resubmitting.
- Design spam (looks like a template) → add real content.
- Privacy policy URL missing or broken.
- Missing Sign in with Apple when you offer another third-party login.
- Permissions requested without explanation in
Info.plist.
Apple's rejection email cites the specific guideline. Fix that exact thing, reply via Resolution Center, resubmit.
Expo Go says "Something went wrong" with no detail
- Shake your phone, tap Debug for the stack trace.
- If the stack trace mentions
Unable to resolve module, a dependency wasn't installed. In Appsanic, click Preview > Restart. - If the error is in a specific file, the agent can usually fix it quickly with: "The preview is crashing with [error]. Fix it."
My screen shows no data, but I can see the data in Supabase
You've probably hit the privacy rules the agent set up. They're doing their job, but a little too aggressively.
The rules say "users only see their own data," and they only know who the user is if the user is signed in at the moment of the query.
Check, in order:
- Is the user actually signed in at the moment the screen loads? Try signing out and back in.
- The data you're trying to show. Is it tagged with the signed-in user's ID? In the Supabase dashboard, click the table and check the
user_idcolumn. - If you added rows manually in the Supabase dashboard, did you remember to set their
user_id? The agent does this automatically; manual rows often miss it.
If you're stuck, mention it to the agent and paste the error or the empty screen. It'll usually spot the issue in one round.
The agent keeps making the same mistake
Patterns that help:
- Restate the constraint explicitly. Sometimes the agent has forgotten an earlier rule. Repeat it in the current prompt.
- Start a new conversation. Old context can accumulate contradictions. Summarize where you are and what you want, fresh.
- Switch models. Fast sometimes misses things Pro catches. And vice versa when a prompt is tightly scoped.
- Ask for a plan. Make the agent surface its assumptions before writing.
My credits burned faster than I expected
Most common causes:
- Using Pro for Fast work. Use Fast on small tweaks. See Fast vs Pro.
- Very long conversations. The agent re-reads context on each turn; past turns add up. Start fresh conversations when you switch topics.
- Ambiguous prompts. Three rounds of clarification cost three times the credits of one good prompt. See Writing Prompts.
- Repeated "continue fixing" rounds. Each one is a paid run. If two rounds have not moved the problem, paste the exact error from your phone instead of asking again - a precise error usually costs one round instead of three.
If you think your usage isn't right, email contact@appsanic.com with a rough timeline. We look at the breakdown and sort it out.
Still stuck
Email contact@appsanic.com with:
- What you expected to happen.
- What actually happened.
- Any error messages, copied as text after removing credentials and personal data.
- Your project URL in Appsanic.
We respond within 1 business day. For security issues, mention "security" in your subject line so we route it quickly.
Next
Read the FAQ for common conceptual questions, or loop back to the Introduction.