FAQ & Troubleshooting for Expo Vibe Coders

Core concepts

1. Metro bundler and cache issues: If changes do not appear or a module cannot be resolved, restart with npx expo start -c, check import paths and reinstall dependencies. — Expo docs
2. Native module not found: Errors such as 'TurboModuleRegistry.getEnforcing' or 'native module not found' mean the library needs a development build rather than Expo Go, or a rebuild after adding it. — Development builds
3. Network request failed: On a phone, localhost is the phone itself. Use your computer's LAN IP, a tunnel, or a hosted dev backend; on the Android emulator use 10.0.2.2. — React Native debugging
4. NativeWind classes not applying: Check global.css is imported once in the root layout, content paths include your folders, Babel and Metro are configured, and restart with a cleared cache. — NativeWind docs
5. Supabase returns empty data: Usually Row Level Security with no matching policy, a missing session, or a wrong user_id. Test the query as the signed-in user. — Supabase RLS
6. EAS build failures: Read the first error in the build log; check SDK and dependency compatibility with npx expo-doctor, Node version and credentials. — EAS Build
7. Store rejections: Common reasons: missing privacy policy, no account deletion, unexplained permissions, crashes on launch, or broken demo accounts. Provide test credentials in review notes. — App Store Review Guidelines

Concept videos

YouTube channels and searches for these topics. On a large screen they open in the reading panel next to the roadmap.

• Fixing Expo errors — Expo channel
• Common React Native errors — YouTube search: common React Native Expo errors and fixes

Explanation

How do I fix 'Unable to resolve module'?

Check the import path and file name casing, make sure the package is installed with npx expo install, restart Metro with npx expo start -c, and delete node_modules and reinstall if it persists.

Why does my app work in Expo Go but crash in the build?

Expo Go bundles a fixed set of native modules; your build includes your own. Check config plugins, permissions, and environment variables, which may differ between environments.

Why are my environment variables undefined?

Only variables prefixed with EXPO_PUBLIC_ reach the client, and they are read at build or bundle time. Restart the dev server after changing .env.

Why does the keyboard cover my input?

Wrap the form in a keyboard-avoiding or keyboard-aware scroll view and test on both platforms, as their behaviour differs.

Why does push notification token return null?

Push needs a physical device, granted permission and correctly configured credentials in a development or production build.

How do I make my AI agent stop looping on an error?

Interrupt it, paste the exact error and the file, ask for a root-cause explanation first, then approve one minimal change.

What Is It?

A troubleshooting guide maps symptoms to likely causes and the smallest fix.

Why Should I Care?

Most lost hours come from a few repeat problems; knowing them keeps momentum.

Real World Analogy

It is a car's dashboard warning-light manual: each light has a known cause and a first check.

Visual Mental Model

Symptom -> likely cause -> first check -> smallest fix

Beginner Explanation

Keep this page open while building. When something breaks, find the symptom, apply the first check, and paste the exact error to your agent.

Smallest Possible Example

npx expo start -c
npx expo-doctor
npx expo install --fix
rm -rf node_modules && npm install

Common Mistakes

❌ Paraphrasing an error to the agent.

Paste the exact message and stack for an accurate diagnosis.

❌ Fixing symptoms in code when the cause is configuration.

Check cache, build type and environment first.

Real Project Example

Support forums for Expo and React Native are full of the same handful of errors; this checklist covers the usual suspects.

Build This Mini Project

Create TROUBLESHOOTING.md in your repo with five errors you hit and their fixes, and link it from AGENTS.md.

Interview Question

An app works in the simulator but a feature fails on a physical device; how do you investigate?

Check permissions, native modules and build type, read device logs, compare environment configuration and use crash reporting to see the stack trace.

Key Takeaways

• Clear the cache first.
• Native errors usually mean a development build.
• RLS silently returns empty results.
• Paste exact errors to your agent.

Stack for this step

Prompts for Cursor, Claude Code & Codex

Paste these into Cursor, Claude Code, Codex, or any coding agent. Replace the bracketed parts with your app details, and keep the agent in plan mode first so you review the approach before it edits files.

Root cause first

Here is the exact error and the relevant file: [paste]. List the three most likely causes ranked by probability, the first check for each, and only then propose the smallest fix. Do not edit until I choose.

Create a troubleshooting doc

Review the last 20 commits and agent conversations for errors we hit. Write TROUBLESHOOTING.md with each symptom, cause and fix in under 5 lines each.

Claude Code skill for this step

Save this as .claude/skills/troubleshoot-expo/SKILL.md in your project so Claude Code loads it automatically when the task matches. The same text works as a Cursor rule or an AGENTS.md section.

---
name: troubleshoot-expo
description: Use when the Expo app fails to start, build or behave on a device.
---
1. Capture the exact error and the environment (Expo Go, dev build, simulator, device).
2. Run the cache, doctor and typecheck commands.
3. Check native module, env var and permission causes before editing code.
4. Propose one minimal change and verify it on the failing environment.

Rules, databases & blogs to use

• Expo SDK upgrade story: real upgrade issues
• Cursor, Codex, Claude Code prompts: debugging prompts
• Testing & QA rules: testing help
• Mobile rules: mobile conventions

Resources

• Expo docs
• React Native debugging
• Sentry React Native

The 60-second story

Your car's dashboard has a handful of warning lights, and each has a known first check: low oil, loose cap, battery. Nobody rebuilds the engine when the gas cap light comes on.

Expo errors work the same way. Stale cache, missing native module, wrong environment variable, locked-down database rules. Each has a first check that takes a minute. You and your agent should run that first check before touching any code.

Mental model: warning light, first check, smallest fix.