Troubleshooting

Before anything else, two commands solve most diagnostics:

kasy doctor    # checks the environment, keys, webhook, and project config
kasy check     # validates the remote backend (secrets, functions, IAM)

Via MCP: "prepare my machine" (prepare_machine), "check the project" (check_project), "what's the project status" (check_status), "run pub get / pods / clean" (fix_project). See Kasy MCP.

And the full log of any run lives in .kasy/run.log: paste it to an AI when you ask for help.

Authentication

Anonymous auth doesn't create a user

Typical error: User profile not found in database.

1. lib/environments.dart → AuthenticationMode.anonymous
2. Firebase: Firebase Console → Authentication → Anonymous enabled, then run kasy deploy before the first boot. Supabase: kasy new enables Allow anonymous sign-ins on the remote project. Check Authentication → Settings if sign-in still fails.
3. Restart the app

Anonymous user created but missing in Supabase Auth

Symptom: onboarding (or Continue without account) finished, a row exists in public.users (the in-app admin shows Anonymous), but Authentication → Users only lists accounts with email (Google, Apple, etc.).

Common cause: the search dropdown on Authentication → Users is set to Email address. Anonymous users have no email, so they disappear from the list even though they were created.

How to confirm:

1. In the search dropdown, pick Unified search (or User ID)
2. Clear the search box
3. Check the footer: Total: X users may be higher than visible rows
4. Look for rows with email -, display name -, and provider Anonymous
5. Copy the UID from Table Editor → users and search by User ID in Auth

Login disappears on the web between runs

Use kasy run --web (port 5555). A random port = the session gets "stuck" on the previous origin.

Google Sign-In fails on the web

Add http://localhost:5555 (and the production domain) in Google Cloud Console → Credentials → OAuth origins.

Firebase: if the error is auth/unauthorized-domain, also add the domain in Firebase Console → Authentication → Settings → Authorized domains. Supabase: the equivalent is Authentication → URL Configuration in the Supabase dashboard — add http://localhost:5555 and the production domain under Site URL / Redirect URLs.

Social login doesn't open in the editor's browser

Embedded browsers (VS Code, Cursor) block the login popup. Test social login in an external Chrome: it works normally in the final app.

Subscriptions (RevenueCat)

INVALID_CREDENTIALS

The app type in RC and the key's prefix don't match: Test Store → test_, App Store → appl_, Google Play → goog_. Details in RevenueCat → Common errors.

Empty paywall in the simulator

Wrong key. The simulator needs RC_TEST_KEY (test_xxx). kasy run injects it automatically.

Products don't show up on the paywall (physical device)

• Identical IDs between the store and RC, character for character
• (iOS) Paid Applications Agreement signed + bank account validated
• (Android) App published to the internal track

Full checklist in RevenueCat.

The subscription "disappeared" during testing

Normal. In Sandbox, monthly lasts 5 min and annual lasts 30 to 60 min. See Sandbox timing.

Webhook returns 401 / the subscriptions table doesn't update

REVENUECAT_WEBHOOK_KEY isn't the same on both sides (backend and RC dashboard), or the header is missing the Bearer prefix. See Webhook key.

Web payments (Stripe)

Empty paywall on the web

There's no active recurring Price, or the key is test mode with live products (or vice versa). See Stripe → Troubleshooting.

Paid but premium didn't activate

Check the webhook logs at Stripe → Webhooks. Common causes: wrong STRIPE_WEBHOOK_SECRET, events not selected, pending deploy.

Push

Push doesn't arrive on iOS

The APNs Key needs to be in Firebase Console → Cloud Messaging. You can only test on a physical device (the simulator doesn't receive push). Step by step in Push Notifications.

The permission dialog doesn't show up again

iOS and Android 13+ only show the native prompt once per install. To test from scratch: kasy reset (simulator/emulator) or turn it off in system Settings (physical device).

Build and running

iOS build failed

kasy ios clean
kasy ios release

The app opens with dev config in release

Missing --dart-define=ENV=prod in the build. kasy ios release already injects it; it's required in manual builds.

Changes in the RC panel/stores don't show up in the app

Hot reload (r) doesn't refetch RevenueCat's data. Use hot restart (R).

See the full Flutter log

kasy run --raw
# or read .kasy/run.log

Web

White bars on Safari on iPhone

Already fixed in the template (web/index.html uses 100dvh). If you customized index.html, restore that snippet.

The login session disappears between runs

Fixed port: kasy run --web uses 5555 for exactly this reason. If 5555 is busy: kasy run --web --web-port 6000 (the session gets tied to the new port).

Didn't find your problem? Run kasy doctor, copy the output plus .kasy/run.log, and paste them to your AI, or check the specific feature's page in the menu.

Last updated on 08/02/2026