Troubleshooting Guide

Common issues and their solutions.

Backend Issues

"Unable to connect to database"

Symptoms: Application fails to start with database connection error

Solutions:

1. Verify PostgreSQL is running:

docker ps | grep postgres

2. Check connection string in backend/.env:

DATABASE_URL=Host=localhost;Database=almafrica;Username=postgres;Password=postgres

3. Test connection manually:

psql -h localhost -U postgres -d almafrica

"Migration pending" errors

Symptoms: Application fails because migrations need to be applied

Solution:

cd backend
dotnet ef database update \
  --project Almafrica.Infrastructure \
  --startup-project Almafrica.API

"Port 5000 already in use"

Symptoms: Backend won't start, port conflict

Solution:

# Find process using port
lsof -i :5000

# Kill the process
kill -9 <PID>

# Or use a different port
dotnet run --project Almafrica.API --urls "http://localhost:5001"

"JWT token invalid"

Symptoms: API returns 401 Unauthorized

Solutions:

1. Check JWT_SECRET matches between backend and web
2. Verify token hasn't expired
3. Clear browser cookies/localStorage and re-login

Web Issues

"Module not found" errors

Symptoms: Build fails with module resolution errors

Solution:

cd web/almafrica-web

# Clear node_modules and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install

"Hydration error"

Symptoms: React hydration mismatch warnings in console

Common causes:

• Using Date.now() or Math.random() in render
• Browser extensions modifying DOM
• Mismatched client/server data

Solution: Wrap client-specific code in useEffect:

const [mounted, setMounted] = useState(false)

useEffect(() => {
  setMounted(true)
}, [])

if (!mounted) return null

"Build fails with type errors"

Symptoms: npm run build fails with TypeScript errors

Solution:

# Run type check to see all errors
pnpm type-check

# Fix errors one by one
# Common issues:
# - Missing type imports
# - Incorrect prop types
# - null/undefined not handled

"API calls failing with CORS"

Symptoms: Browser blocks API requests

Solution:

1. Verify backend CORS settings include your origin
2. Check NEXT_PUBLIC_API_URL is correct
3. For development, ensure backend allows http://localhost:3000

Mobile Issues

"Flutter doctor shows issues"

Symptoms: flutter doctor shows warnings/errors

Solution:

# Run with verbose output
flutter doctor -v

# Common fixes:
# - Install missing Android SDK components
# - Accept Android licenses: flutter doctor --android-licenses
# - Install Xcode (macOS): xcode-select --install

"App crashes on startup"

Symptoms: App launches then immediately closes

Solutions:

1. Check logs:

flutter logs

2. Common causes:

   • Missing permissions in AndroidManifest.xml / Info.plist
   • Invalid API endpoint
   • Database migration issue

3. Clean and rebuild:

flutter clean
flutter pub get
flutter run

"Sync not working offline"

Symptoms: Data doesn't sync when app comes back online

Solutions:

1. Check connectivity listener is active
2. Verify SQLite database exists and has pending records
3. Check API endpoint is reachable
4. Review sync logs in debug console

"Hot reload not working"

Symptoms: Code changes don't reflect in app

Solutions:

1. Ensure running in debug mode:

flutter run --debug

2. Try hot restart instead (press R in terminal)
3. If still not working, stop and restart app

Database Issues

"Too many connections"

Symptoms: PostgreSQL connection limit reached

Solution:

# Check active connections
psql -c "SELECT count(*) FROM pg_stat_activity;"

# Kill idle connections
psql -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE state = 'idle';"

# Increase max connections in postgresql.conf if needed

"Migration rollback fails"

Symptoms: dotnet ef database update to previous migration fails

Solution:

1. Check the Down() method is correct
2. Manually revert changes if needed
3. In extreme cases, recreate database:

dotnet ef database drop --force
dotnet ef database update

Docker Issues

"Container won't start"

Symptoms: Docker container exits immediately

Solution:

# Check logs
docker logs <container_name>

# Common issues:
# - Port already in use
# - Volume mount issues
# - Environment variables missing

"Volume permission denied"

Symptoms: Docker can't write to mounted volumes

Solution (Linux):

# Add user to docker group
sudo usermod -aG docker $USER

# Fix volume permissions
sudo chown -R $USER:$USER ./data

Git Issues

"Merge conflict"

Symptoms: Git reports conflicts during merge/rebase

Solution:

# See conflicted files
git status

# Open each file and look for <<<<<<< HEAD markers

# After resolving
git add <resolved-file>
git commit  # or git rebase --continue

"Accidentally committed to main"

Symptoms: Commits on main that should be on a branch

Solution:

# Create branch from current state
git branch feature/my-changes

# Reset main to origin
git reset --hard origin/main

# Switch to feature branch
git checkout feature/my-changes

"Push rejected (non-fast-forward)"

Symptoms: Can't push because remote has new commits

Solution:

# Pull and rebase your commits on top
git pull --rebase origin main

# Resolve any conflicts
# Then push
git push origin feature/my-branch

Performance Issues

Backend slow responses

Diagnosis:

# Enable detailed logging
export ASPNETCORE_ENVIRONMENT=Development

# Check database query performance
# Add logging to EF Core queries

Common fixes:

• Add missing indexes
• Use AsNoTracking() for read-only queries
• Implement caching for frequently accessed data

Web slow loading

Diagnosis:

1. Check Network tab in DevTools
2. Run Lighthouse audit

Common fixes:

• Optimize images
• Use dynamic imports for large components
• Enable Next.js image optimization

Mobile app laggy

Diagnosis:

# Run in profile mode
flutter run --profile

# Use Flutter DevTools
flutter pub global activate devtools
flutter pub global run devtools

Common fixes:

• Avoid rebuilds with const widgets
• Use ListView.builder for long lists
• Offload heavy work to isolates

Still Stuck?

1. Search GitHub Issues
2. Check Stack Overflow
3. Ask in team chat (#engineering)
4. Create a new issue with:
   • Steps to reproduce
   • Expected behavior
   • Actual behavior
   • Logs/screenshots