Troubleshooting

Common issues and solutions when using App Factory.

Quick Diagnostics

Start with these commands to understand the current state:

show status
validate run

Common Issues

Pipeline stops with schema validation error

Symptoms
  • • Error message mentions schema validation failure
  • • Stage JSON file is incomplete or malformed
Solutions
  • • Check the error message for specific field violations
  • • Review the stage JSON against the schema in schemas/
  • • Re-run the failing stage - validation failures are recoverable

Build command can't find idea

Symptoms
  • • Error: Idea not found in idea bin
  • • Slug or name doesn't match any generated ideas
Solutions
  • • Run 'show status' to see available ideas
  • • Check the idea_index.json for correct slugs
  • • Use the exact slug or name alias from stage01.json

Stage 10 fails with missing artifacts

Symptoms
  • • Build process starts but fails quickly
  • • Error mentions missing stage files (02-09)
Solutions
  • • Ensure all prerequisite stages completed successfully
  • • Run 'validate run' to check artifact completeness
  • • The build command will run missing stages automatically

Generated app won't start

Symptoms
  • • Expo CLI throws errors on start
  • • Metro bundler fails to compile
Solutions
  • • Delete node_modules and run 'npm install'
  • • Run 'npx expo install --check' to fix dependency versions
  • • Check app.json for valid configuration
  • • Ensure bundle identifier is properly set

RevenueCat integration issues

Symptoms
  • • Paywall doesn't load offerings
  • • Purchase flow fails silently
Solutions
  • • Verify EXPO_PUBLIC_REVENUECAT_API_KEY is set
  • • Check RevenueCat dashboard for product configuration
  • • Ensure offerings are properly set up in RevenueCat
  • • Review the generated services/revenuecat.ts file

iOS Simulator won't launch

Symptoms
  • • Preview dashboard shows iOS not ready
  • • Simulator list is empty
Solutions
  • • Ensure Xcode is installed from App Store
  • • Install iOS simulators via Xcode > Preferences > Components
  • • Run: xcrun simctl list devices iOS available
  • • Boot a simulator manually: xcrun simctl boot 'iPhone 16 Pro'

Quality gate validation fails

Symptoms
  • • Pipeline stops at gate 02.5, 02.7, 09.5, or 10.1
  • • Error mentions incomplete specifications
Solutions
  • • Review the gate's validation criteria
  • • Check that preceding stages produced complete artifacts
  • • Quality gates are strict by design - fix upstream issues first

Leaderboard update fails

Symptoms
  • • Stage 01 completes but leaderboard shows error
  • • leaderboard_failure.md file created
Solutions
  • • Check leaderboards/ directory permissions
  • • Verify the raw leaderboard JSON structure
  • • Review the failure file for specific remediation steps

Getting Help

If you're still stuck after trying the solutions above:

  • • Check the FAQ for common questions
  • • Review the generated execution logs in runs/.../outputs/
  • • Check failure artifacts for detailed error information
  • • Open an issue on GitHub with the error details and relevant logs