Troubleshooting

Find the symptom you see during setup, then check the configuration it depends on.

Cloning returns a 404 or permission error

Check that you have accepted the repository invitation and that your terminal uses the GitHub account with access. If you use SSH, add --ssh to the scaffold command.

The app closes at launch or reports a missing Supabase key

For local development, set EXPO_PUBLIC_SUPABASE_URL and EXPO_PUBLIC_SUPABASE_ANON_KEY in .env.local, then restart the development server and reload the app.

For a cloud build, check the environment selected by its eas.json profile. Local .env.local values are excluded from the upload. Add the values to the matching EAS environment and create a new build.

An iOS build made with Xcode 27 closes the moment it opens

The device log says UIScene life cycle is required for apps built with this SDK. The iOS 27 SDK only launches apps that use the UIKit scene lifecycle, and app.config.js turns it on with enableSceneSupport: true under expo-build-properties → ios.

Restore the setting if it was removed, run npx expo install --fix, then rebuild. The setting needs expo 57.0.23 and expo-build-properties 57.0.20 or newer; older SDK 57 patch releases do not know it. See Xcode 27 and the iOS 27 SDK.

Picking a photo crashes the app on iOS 27.1

On iOS 27.1, the app crashes the moment a photo is picked from the library in chat or scan. expo-image-picker on Expo SDK 57 runs into an iOS 27.1 bug when a photo is picked without cropping. The avatar picker crops, so it is not affected.

The fix is in Expo SDK 58 only (expo/expo#50435 ). No picker option avoids the crash without forcing a crop on every pick, so it stays until the app moves to SDK 58.

The confirmation email does not arrive

The app supports email confirmation. Check the email address, delivery configuration and redirect URLs in Authentication. A successful sign-up request does not prove the email was delivered.

Chat does not return a reply

Check function deployment and the OpenRouter secret. A missing key returns provider_not_configured; an invalid key or insufficient provider credit can fail after streaming starts. The app shows an error with a retry action.

Use a free model and an account with quota available. yarn skills:doctor can check secret metadata when your CLI is signed in and linked, but it does not send a model request.

To test the deployed function, run the bundled verifier with an existing test account that has confirmed its email:

node .claude/skills/setup/scripts/verify-ai.mjs --email "you@example.com" --password "your-test-account-password"

The script sends a real message and can consume provider credit and free quota. It also records AI consent on the account when the account has none or an older version, which is why it should be a test account. Look for the message that the model streamed a response. A quota refusal confirms that the function responded, but it does not test the provider. Without credentials, the script checks only reachability. --help lists its flags, and a misspelt flag stops the run with exit code 2 rather than being ignored.

For a failure the script cannot explain, open the function’s logs in the Supabase Dashboard. See Chat error codes.

Every request is refused with Legacy API keys are disabled

The project’s legacy API keys are off, and either the app still ships the legacy anon key (eyJ…) or the deployed functions are older than the code in your project. yarn skills:doctor reports the first case.

Turn the legacy keys back on in the Supabase dashboard to restore service, then follow Replace the legacy Supabase keys in order.

A query on a table you added fails with 42501 permission denied for table

The table has no grant for the role making the request. Supabase does not add one when a table is created, and that applies to service_role in the edge functions as well as to the app. Add the grants in a new migration, following Grant access to a new table.

A deployed function answers Invalid JWT after you rotate JWT signing keys

Supabase checks the caller’s token before a deployed function runs. If the functions start answering Invalid JWT after you move the project to asymmetric JWT signing keys, turn that check off for the four functions and redeploy them:

[functions.chat]
verify_jwt = false
 
[functions.generate]
verify_jwt = false
 
[functions.identify]
verify_jwt = false
 
[functions.delete-account]
verify_jwt = false

Each function authenticates the caller itself as its first statement, so a request without a valid session is still refused.

xcode-select: error: tool ‘xcodebuild’ requires Xcode

This error means the selected developer directory points at Command Line Tools instead of a full Xcode installation. Install and open Xcode , then select its developer directory. For the standard application path:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
xcodebuild -version

Use your actual Xcode path if it is installed elsewhere. See Apple’s command-line tools settings .

Expo cannot detect Xcode

Open Xcode once to complete installation, accept its license and install the simulator runtime. Check the selected developer directory with xcode-select --print-path. If it points to Command Line Tools, use the command in the section above.

No products or offerings are available from RevenueCat

Check the store products, RevenueCat offering and the key for the platform you are testing. The failure can have several causes, including store agreements or mismatched product identifiers. Follow Payment troubleshooting for the checks and the expected sandbox setup.