crowd-funder-from-jason/docs/build-troubleshooting.md

# Build Systems Troubleshooting Guide

**Author**: Matthew Raymer
**Date**: 2025-07-11
**Status**: ✅ **COMPLETE** - Comprehensive troubleshooting for all build systems

## Overview

This guide provides comprehensive troubleshooting for all TimeSafari build systems, including common issues, solutions, and debugging techniques for web, Android, iOS, and Electron builds.

## Quick Diagnostic Commands

### Environment Check
```bash
# Check Node.js and npm versions
node --version
npm --version

# Check platform-specific tools
npx cap --version
npx vite --version

# Check environment variables
echo $VITE_PLATFORM
echo "PWA: automatically enabled for web platforms"
```

### Build System Status
```bash
# Check all build scripts exist
ls -la scripts/build-*.sh

# Check package.json scripts
npm run | grep build:

# Check build artifacts
ls -la dist/
ls -la android/app/build/
ls -la electron/dist/
```

## Web Build Issues

### Development Server Problems

#### Port Already in Use
```bash
# Check what's using port 8080
lsof -i :8080

# Kill the process
kill -9 <PID>

# Or use different port
npm run build:web:dev -- --port 8081
```

#### Hot Reload Not Working
```bash
# Clear browser cache
# DevTools > Application > Storage > Clear site data

# Restart dev server
npm run build:web:dev

# Check file watching
# Ensure no file system watcher limits
```

#### PWA Issues in Development
```bash
# Clear service worker
# DevTools > Application > Service Workers > Unregister

# Clear browser cache
# DevTools > Application > Storage > Clear site data

# Restart development server
npm run build:web:dev
```

### Production Build Issues

#### Build Fails with Errors
```bash
# Clean build artifacts
rm -rf dist/

# Clear npm cache
npm cache clean --force

# Reinstall dependencies
rm -rf node_modules/
npm install

# Rebuild
npm run build:web:prod
```

#### Large Bundle Size
```bash
# Analyze bundle
npm run build:web:prod
# Check dist/assets/ for large files

# Enable bundle analysis
npm install --save-dev vite-bundle-analyzer
# Add to vite.config.web.mts
```

#### PWA Not Working in Production
```bash
# Check manifest generation
ls -la dist/manifest.webmanifest

# Check service worker
ls -la dist/sw.js

# Verify HTTPS (required for PWA)
# Ensure site is served over HTTPS
```

### Docker Build Issues

#### Docker Build Fails
```bash
# Check Docker is running
docker --version
docker ps

# Clean Docker cache
docker system prune -a

# Rebuild without cache
docker build --no-cache -t timesafari-web:production .
```

#### Docker Image Too Large
```bash
# Use multi-stage builds
# Optimize base images
# Remove unnecessary files

# Analyze image layers
docker history timesafari-web:production
```

## Android Build Issues

### Build Process Failures

#### Gradle Build Fails
```bash
# Clean Gradle cache
cd android && ./gradlew clean && cd ..

# Clear Android build cache
rm -rf android/app/build/
rm -rf android/.gradle/

# Rebuild
npm run build:android:dev
```

#### Capacitor Sync Issues
```bash
# Clean Capacitor
npx cap clean android

# Reinstall Android platform
npx cap remove android
npx cap add android

# Sync manually
npx cap sync android
```

#### Resource Generation Fails
```bash
# Check source assets
ls -la assets/icon.png
ls -la assets/splash.png

# Regenerate assets
npx capacitor-assets generate --android

# Check generated resources
ls -la android/app/src/main/res/
```

### Device Deployment Issues

#### No Device Connected
```bash
# Check device connection
adb devices

# Enable USB debugging
# Settings > Developer options > USB debugging

# Install ADB drivers (Windows)
# Download from Google USB drivers
```

#### Device Unauthorized
```bash
# Check device for authorization dialog
# Tap "Allow USB debugging"

# Reset ADB
adb kill-server
adb start-server

# Check device again
adb devices
```

#### APK Installation Fails
```bash
# Uninstall existing app
adb uninstall app.timesafari.app

# Install fresh APK
adb install -r android/app/build/outputs/apk/debug/app-debug.apk

# Check installation
adb shell pm list packages | grep timesafari
```

### Performance Issues

#### Slow Build Times
```bash
# Enable Gradle daemon
# Add to ~/.gradle/gradle.properties:
org.gradle.daemon=true
org.gradle.parallel=true
org.gradle.configureondemand=true

# Use incremental builds
# Only rebuild changed files
```

#### Large APK Size
```bash
# Enable APK splitting
# Add to android/app/build.gradle:
android {
    splits {
        abi {
            enable true
            reset()
            include 'x86', 'x86_64', 'arm64-v8a', 'armeabi-v7a'
        }
    }
}
```

## Electron Build Issues

### Development Issues

#### App Won't Start
```bash
# Check Electron installation
npm list electron

# Clear Electron cache
rm -rf ~/.config/TimeSafari/
rm -rf ~/Library/Application\ Support/TimeSafari/
rm -rf %APPDATA%\TimeSafari

# Reinstall Electron
npm install electron
```

#### Single Instance Lock Issues
```bash
# Check lock file
ls -la ~/.timesafari-lock

# Remove lock file manually
rm -f ~/.timesafari-lock

# Restart app
npm run build:electron:dev
```

#### Database Issues
```bash
# Clear database
./scripts/clear-database.sh

# Check database files
ls -la ~/.config/TimeSafari/
ls -la ~/Library/Application\ Support/TimeSafari/

# Rebuild database
npm run build:electron:dev
```

### Package Build Issues

#### Package Creation Fails
```bash
# Check electron-builder
npm list electron-builder

# Clean package cache
rm -rf electron/dist/
rm -rf electron/node_modules/

# Reinstall dependencies
cd electron && npm install && cd ..

# Rebuild package
npm run build:electron:appimage:prod
```

#### Code Signing Issues
```bash
# Check certificates
# macOS: Keychain Access
# Windows: Certificate Manager
# Linux: Check certificate files

# Skip code signing for testing
# Add to electron-builder.config.json:
"forceCodeSigning": false
```

#### Platform-Specific Issues

##### Linux AppImage Issues
```bash
# Check AppImage creation
file electron/dist/*.AppImage

# Make executable
chmod +x electron/dist/*.AppImage

# Test AppImage
./electron/dist/*.AppImage
```

##### macOS DMG Issues
```bash
# Check DMG creation
file electron/dist/*.dmg

# Mount DMG
hdiutil attach electron/dist/*.dmg

# Check contents
ls -la /Volumes/TimeSafari/
```

##### Windows EXE Issues
```bash
# Check EXE creation
file electron/dist/*.exe

# Test installer
# Run the EXE file
# Check installation directory
```

## iOS Build Issues (Future)

### Xcode Issues
```bash
# Check Xcode installation
xcode-select --print-path

# Install command line tools
xcode-select --install

# Accept Xcode license
sudo xcodebuild -license accept
```

### Simulator Issues
```bash
# List available simulators
xcrun simctl list devices

# Boot simulator
xcrun simctl boot "iPhone 15 Pro"

# Reset simulator
xcrun simctl erase all
```

### Code Signing Issues
```bash
# Check certificates
security find-identity -v -p codesigning

# Check provisioning profiles
ls ~/Library/MobileDevice/Provisioning\ Profiles/

# Install certificate
# Use Keychain Access or Xcode
```

## Environment Issues

### Environment Variables

#### Missing Environment Variables
```bash
# Check environment files
ls -la .env*

# Set required variables
export VITE_PLATFORM=web

# Check in build script
echo $VITE_PLATFORM
echo "PWA: automatically enabled for web platforms"
```

#### Wrong Environment Loaded
```bash
# Check current environment
echo $NODE_ENV

# Force environment
NODE_ENV=production npm run build:web:prod

# Check environment file loading
# Verify .env.production exists
```

### Dependency Issues

#### Missing Dependencies
```bash
# Check package.json
cat package.json | grep -A 10 "dependencies"

# Install missing dependencies
npm install

# Check for peer dependencies
npm ls
```

#### Version Conflicts
```bash
# Check for conflicts
npm ls

# Update dependencies
npm update

# Force resolution
npm install --force
```

#### Platform-Specific Dependencies
```bash
# Check Capacitor plugins
npx cap ls

# Install missing plugins
npm install @capacitor/core @capacitor/cli

# Sync plugins
npx cap sync
```

## Performance Issues

### Build Performance

#### Slow Build Times
```bash
# Enable parallel processing
# Add to package.json scripts:
"build:parallel": "npm run build:web:prod & npm run build:android:prod & wait"

# Use incremental builds
# Only rebuild changed files

# Optimize file watching
# Increase file watcher limits
```

#### Memory Issues
```bash
# Increase Node.js memory
NODE_OPTIONS="--max-old-space-size=4096" npm run build:web:prod

# Check memory usage
top -p $(pgrep node)

# Optimize build process
# Use streaming builds
# Minimize memory usage
```

### Runtime Performance

#### App Performance Issues
```bash
# Profile application
# Use browser DevTools > Performance
# Use React/Vue DevTools

# Check bundle size
npm run build:web:prod
# Analyze dist/assets/

# Optimize code splitting
# Implement lazy loading
```

## Debugging Techniques

### Verbose Logging

#### Enable Verbose Mode
```bash
# Web builds
./scripts/build-web.sh --verbose

# Android builds
./scripts/build-android.sh --verbose

# Electron builds
./scripts/build-electron.sh --verbose
```

#### Debug Environment
```bash
# Enable debug logging
DEBUG_MIGRATIONS=1 npm run build:web:dev

# Check debug output
# Look for detailed error messages
# Check console output
```

### Log Analysis

#### Build Logs
```bash
# Capture build logs
npm run build:web:prod > build.log 2>&1

# Analyze logs
grep -i error build.log
grep -i warning build.log

# Check for specific issues
grep -i "failed\|error\|exception" build.log
```

#### Runtime Logs

##### Web Browser
```bash
# Open DevTools
# Console tab for JavaScript errors
# Network tab for API issues
# Application tab for storage issues
```

##### Android
```bash
# View Android logs
adb logcat | grep -i timesafari

# Filter by app
adb logcat | grep -i "app.timesafari.app"
```

##### Electron
```bash
# View Electron logs
# Check console output
# Check DevTools console
# Check main process logs
```

## Common Error Messages

### Web Build Errors

#### "Module not found"
```bash
# Check import paths
# Verify file exists
# Check case sensitivity
# Update import statements
```

#### "Port already in use"
```bash
# Kill existing process
lsof -i :8080
kill -9 <PID>

# Use different port
npm run build:web:dev -- --port 8081
```

### Android Build Errors

#### "Gradle build failed"
```bash
# Clean Gradle cache
cd android && ./gradlew clean && cd ..

# Check Gradle version
./android/gradlew --version

# Update Gradle wrapper
cd android && ./gradlew wrapper --gradle-version 8.13 && cd ..
```

#### "Device not found"
```bash
# Check device connection
adb devices

# Enable USB debugging
# Settings > Developer options > USB debugging

# Install drivers (Windows)
# Download Google USB drivers
```

### Electron Build Errors

#### "App already running"
```bash
# Remove lock file
rm -f ~/.timesafari-lock

# Kill existing processes
pkill -f "TimeSafari"

# Restart app
npm run build:electron:dev
```

#### "Code signing failed"
```bash
# Check certificates
# macOS: Keychain Access
# Windows: Certificate Manager

# Skip code signing for testing
# Add to electron-builder.config.json:
"forceCodeSigning": false
```

## Prevention Strategies

### Best Practices

#### Regular Maintenance
```bash
# Update dependencies regularly
npm update

# Clean build artifacts
npm run clean:all

# Check for security vulnerabilities
npm audit

# Update build tools
npm update -g @capacitor/cli
npm update -g electron-builder
```

#### Environment Management
```bash
# Use consistent environments
# Separate dev/test/prod configurations
# Version control environment files
# Document environment requirements
```

#### Testing
```bash
# Test builds regularly
npm run build:web:prod
npm run build:android:prod
npm run build:electron:prod

# Test on different platforms
# Verify all features work
# Check performance metrics
```

### Monitoring

#### Build Monitoring
```bash
# Track build times
# Monitor build success rates
# Check for performance regressions
# Monitor bundle sizes
```

#### Runtime Monitoring
```bash
# Monitor app performance
# Track error rates
# Monitor user experience
# Check platform-specific issues
```

---

**Last Updated**: 2025-07-11
**Version**: 1.0.3-beta
**Status**: Production Ready