Skip to main content

Troubleshooting

This guide covers common issues you might encounter while developing BookWish and their solutions.

Database Issues​

Can't Connect to PostgreSQL​

Error: P1001: Can't reach database server at [host]

Causes & Solutions:

  1. PostgreSQL not running

    # Check if PostgreSQL is running
    pg_isready

    # Start PostgreSQL
    # macOS with Homebrew:
    brew services start postgresql@15

    # Linux:
    sudo systemctl start postgresql

  2. Wrong DATABASE_URL format

    # Correct format:
    DATABASE_URL=postgresql://[user]:[password]@[host]:[port]/[database]

    # Example:
    DATABASE_URL=postgresql://postgres:password@localhost:5432/bookwish

  3. Database doesn't exist

    # Create database
    createdb bookwish

    # Or using psql:
    psql postgres
    CREATE DATABASE bookwish;

  4. Authentication failed

    • Check username and password in DATABASE_URL
    • For Supabase, use the correct password from your dashboard
    • Verify user has permissions: GRANT ALL PRIVILEGES ON DATABASE bookwish TO postgres;

  5. Supabase connection issues

    • Use "Direct connection" URL for migrations
    • Use "Pooled connection" URL for application runtime
    • Check IP allowlist in Supabase dashboard
    • Verify project is not paused (free tier)

Migration Failures​

Error: Migration failed to apply cleanly to the shadow database

Solutions:

cd backend

# Reset database (development only - deletes all data!)
npx prisma migrate reset

# Or force migrate
npx prisma migrate deploy

# Regenerate Prisma client
npm run prisma:generate

Error: The table 'users' already exists

This happens if migrations are out of sync. Solutions:

# Mark migrations as applied without running them
npx prisma migrate resolve --applied [migration-name]

# Or reset and re-run
npx prisma migrate reset

Prisma Client Out of Sync​

Error: Prisma Client not initialized or Unknown field 'fieldName'

Solution:

cd backend

# Regenerate Prisma Client
npm run prisma:generate

# Restart development server
npm run dev

Database Connection Pool Exhausted​

Error: Error: Can't reach database server. Connection pool exhausted.

Solutions:

  1. Check for unclosed connections

    • Ensure you're not creating new PrismaClient instances
    • Use singleton pattern (already configured in the codebase)

  2. Increase connection pool size (if using Supabase)

    • Upgrade to paid tier for more connections
    • Use connection pooling (PgBouncer)

  3. Restart backend

    # Kill backend process
    pkill -f "ts-node"

    # Restart
    npm run dev

Redis Issues​

Can't Connect to Redis​

Error: Error: connect ECONNREFUSED 127.0.0.1:6379

Solutions:

  1. Redis not running

    # Check if Redis is running
    redis-cli ping

    # Start Redis
    # macOS with Homebrew:
    brew services start redis

    # Linux:
    sudo systemctl start redis

    # Or run in foreground:
    redis-server

  2. Wrong REDIS_URL

    # Local Redis
    REDIS_URL=redis://localhost:6379

    # Remote Redis (Railway, Upstash)
    REDIS_URL=redis://default:password@host:port

  3. Redis port conflict

    # Check what's using port 6379
    lsof -i:6379

    # Or use different port
    redis-server --port 6380
    REDIS_URL=redis://localhost:6380

Redis Connection Timeout​

Error: Redis connection timeout

Solutions:

  • Check firewall settings
  • Increase timeout in Redis client configuration
  • Use local Redis for development instead of remote

Clear Redis Cache​

If you're seeing stale data:

# Clear all Redis data
redis-cli FLUSHALL

# Or connect and flush
redis-cli
> FLUSHALL
> exit

Flutter Build Issues​

Build Runner Conflicts​

Error: Conflicting outputs were detected and the build is unable to prompt for permission to remove them

Solution:

cd app

# Use delete-conflicting-outputs flag
flutter pub run build_runner build --delete-conflicting-outputs

# Or clean first
flutter clean
flutter pub get
flutter pub run build_runner build --delete-conflicting-outputs

Build Runner Generation Failures​

Error: [SEVERE] Failed to build

Common causes:

  1. Syntax error in annotated file

    • Check the file mentioned in error
    • Fix Dart syntax errors
    • Ensure @riverpod annotations are correct

  2. Missing dependencies

    flutter pub get

  3. Outdated generated files

    # Delete all generated files
    find . -name "*.g.dart" -delete

    # Regenerate
    flutter pub run build_runner build --delete-conflicting-outputs

iOS Build Errors​

Error: CocoaPods not installed or pod install failed

Solutions:

  1. Install CocoaPods

    sudo gem install cocoapods

  2. Update pods

    cd app/ios
    rm -rf Pods Podfile.lock
    pod install --repo-update
    cd ../..

  3. Clean and rebuild

    flutter clean
    cd app/ios
    pod install
    cd ../..
    flutter run

Error: No signing certificate "iOS Development" found

Solutions:

  • Open app/ios/Runner.xcworkspace in Xcode
  • Select Runner > Signing & Capabilities
  • Choose your development team
  • Enable "Automatically manage signing"

Error: Module 'firebase_core' not found

Solution:

cd app/ios
rm -rf Pods Podfile.lock .symlinks
pod install
cd ../..
flutter clean
flutter pub get
flutter run

Android Build Errors​

Error: SDK location not found

Solutions:

  1. Set ANDROID_HOME

    # macOS/Linux (add to ~/.zshrc or ~/.bashrc)
    export ANDROID_HOME=$HOME/Library/Android/sdk
    export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

    # Or create local.properties
    echo "sdk.dir=$HOME/Library/Android/sdk" > app/android/local.properties

  2. Accept Android licenses

    flutter doctor --android-licenses

Error: Gradle build failed

Solutions:

  1. Clean Gradle cache

    cd app/android
    ./gradlew clean
    cd ../..
    flutter clean
    flutter pub get

  2. Update Gradle wrapper

    cd app/android
    ./gradlew wrapper --gradle-version=8.0
    cd ../..

  3. Check Java version

    java -version
    # Should be Java 11 or higher

Error: Execution failed for task ':app:processDebugGoogleServices'

Solutions:

  • Verify google-services.json is in app/android/app/
  • Ensure it's valid JSON (download fresh from Firebase Console)
  • Check that package name matches your app

Flutter Doctor Issues​

Warning: Android toolchain - develop for Android devices

Solutions:

# Install Android SDK
flutter doctor --android-licenses

# Or install Android Studio
# Download from: https://developer.android.com/studio

Warning: Xcode - develop for iOS and macOS

Solutions (macOS only):

# Install Xcode from App Store
# Then run:
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch
sudo xcodebuild -license accept

Backend Build Issues​

TypeScript Compilation Errors​

Error: TSError: ⨯ Unable to compile TypeScript

Solutions:

  1. Check for syntax errors

    npm run lint

  2. Clear node_modules

    rm -rf node_modules package-lock.json
    npm install

  3. Update TypeScript

    npm install typescript@latest

Missing Dependencies​

Error: Cannot find module 'moduleName'

Solutions:

# Install missing dependency
npm install moduleName

# Or reinstall all dependencies
rm -rf node_modules package-lock.json
npm ci

Port Already in Use​

Error: Error: listen EADDRINUSE: address already in use :::3000

Solutions:

  1. Kill process on port 3000

    # Find process
    lsof -ti:3000

    # Kill it
    kill -9 $(lsof -ti:3000)

    # Or on Windows:
    netstat -ano | findstr :3000
    taskkill /PID [PID] /F

  2. Use different port

    PORT=3001 npm run dev

Environment Variable Validation Errors​

Error: Environment validation failed: JWT_SECRET: String must contain at least 32 character(s)

Solution:

  • Open backend/.env
  • Generate secure secrets: 
    # Generate JWT_SECRET
    openssl rand -hex 32

    # Generate JWT_REFRESH_SECRET
    openssl rand -hex 32

    # Add to .env file
    JWT_SECRET=generated_secret_here
    JWT_REFRESH_SECRET=another_generated_secret_here

API Integration Issues​

Firebase Push Notifications Not Working​

Symptoms:

  • Push notifications not sending
  • firebase.not_initialized in logs

Solutions:

  1. Check environment variables

    # Required in backend/.env:
    FIREBASE_PROJECT_ID=your-project-id
    FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour key\n-----END PRIVATE KEY-----\n"
    FIREBASE_CLIENT_EMAIL=firebase-adminsdk-xxxxx@your-project.iam.gserviceaccount.com

  2. Private key format

    • In .env, use literal \n (two characters)
    • Code will replace \\n with actual newlines
    • Don't escape the newlines in environment variables

  3. Generate new credentials

    • Firebase Console > Project Settings > Service Accounts
    • Click "Generate new private key"
    • Copy values to .env

Stripe Webhook Failures​

Error: Webhook signature verification failed

Solutions:

  1. Use Stripe CLI for local testing

    # Install Stripe CLI
    brew install stripe/stripe-cli/stripe

    # Login
    stripe login

    # Forward webhooks to local backend
    stripe listen --forward-to localhost:3000/v1/webhooks/stripe

    # Copy webhook signing secret to .env
    STRIPE_WEBHOOK_SECRET=whsec_...

  2. Verify webhook secret

    • Check Stripe Dashboard > Developers > Webhooks
    • Copy signing secret to STRIPE_WEBHOOK_SECRET

Square OAuth Errors​

Error: Encryption key required for Square OAuth

Solution:

# Generate encryption key
openssl rand -base64 32

# Add to backend/.env
ENCRYPTION_KEY=generated_key_here

Network & Connectivity Issues​

Flutter App Can't Connect to Backend​

Symptoms:

  • API calls failing with connection errors
  • Timeouts or "unable to connect"

Solutions:

  1. Check backend is running

    curl http://localhost:3000/health

  2. iOS Simulator: Use localhost

    // In app configuration
    baseUrl: 'http://localhost:3000'

  3. Android Emulator: Use 10.0.2.2

    // In app configuration
    baseUrl: 'http://10.0.2.2:3000'

  4. Physical Device: Use computer's IP

    # Find your IP
    ifconfig | grep "inet "

    # Use in app (example)
    baseUrl: 'http://192.168.1.100:3000'

  5. Check firewall settings

    • Allow incoming connections on port 3000
    • Disable VPN if causing issues

CORS Errors (Web)​

Error: Access to fetch at 'http://localhost:3000' from origin 'http://localhost:3001' has been blocked by CORS

Solutions:

  1. Backend already has CORS configured

    • Check backend/src/index.ts for CORS middleware
    • Should allow localhost origins in development

  2. Verify origin is allowed

    // In backend/src/index.ts
    app.use(cors({
      origin: ['http://localhost:3001', 'http://localhost:3002'],
      credentials: true
    }));

Performance Issues​

Slow Backend Startup​

Symptoms:

  • Backend takes a long time to start
  • Database connection timeouts

Solutions:

  1. Check PostgreSQL is responsive

    psql $DATABASE_URL -c "SELECT 1"

  2. Use local Redis

    • Remote Redis can be slow
    • Use redis://localhost:6379 for development

  3. Check for large migrations

    • Large seed data can slow startup
    • Comment out seed in prisma:migrate script during development

Slow Flutter Build Times​

Solutions:

  1. Stop build_runner watch

    • Only run when needed
    • Use manual builds for faster iteration

  2. Clean build cache periodically

    flutter clean

  3. Use physical device instead of simulator

    • Physical devices often run faster
    • Less overhead than emulator

  4. Optimize code generation

    • Only annotate what needs to be generated
    • Remove unused generated files

Development Environment Issues​

VS Code Flutter Extension Issues​

Symptoms:

  • Code completion not working
  • Flutter commands not available

Solutions:

  1. Reload VS Code

    • Command Palette > Developer: Reload Window

  2. Verify Flutter SDK path

    • Command Palette > Flutter: Change SDK
    • Point to your Flutter installation

  3. Reinstall extensions

    • Uninstall Flutter and Dart extensions
    • Restart VS Code
    • Reinstall extensions

Git Issues​

Error: Your branch is behind 'origin/main'

Solution:

git pull origin main

Error: Merge conflict in [file]

Solution:

# View conflicts
git status

# Edit files to resolve conflicts
# Then:
git add .
git commit -m "Resolve merge conflicts"

Getting Help​

If you're still experiencing issues:

  1. Check GitHub Issues

    • Search existing issues
    • Create new issue with full error details

  2. Check Logs

    • Backend: Terminal output from npm run dev
    • Flutter: Terminal output from flutter run
    • Database: npx prisma studio for data inspection

  3. Use Debug Mode

    # Backend with verbose logging
    DEBUG=* npm run dev

    # Flutter with verbose output
    flutter run -v

  4. Provide Error Context When asking for help, include:

    • Full error message
    • Commands that caused the error
    • Operating system and versions
    • Relevant configuration (without secrets!)

Prevention Tips​

  1. Keep dependencies updated

    # Backend
    cd backend && npm outdated

    # Flutter
    cd app && flutter pub outdated

  2. Use version control

    • Commit working state frequently
    • Create branches for experiments
    • Use .gitignore for build artifacts

  3. Regular maintenance

    # Clean Flutter build cache weekly
    flutter clean

    # Clear Redis cache when switching branches
    redis-cli FLUSHALL

    # Reset database when schema changes
    npx prisma migrate reset

  4. Monitor logs

    • Watch for warnings
    • Address deprecations early
    • Keep error tracking enabled

Next Steps​