Troubleshooting

Solutions for common issues and platform-specific problems

Troubleshooting Guide

This guide helps you resolve common issues you might encounter while developing or using Remind Tools applications.

Quick Solutions

Common Issues

General problems and their solutions

Platform Specific

iOS, Android, Web, and Desktop issues

Frequently Encountered Issues

Development Environment

Melos bootstrap fails

Problem: melos bootstrap command fails with dependency errors.

Solution:

# Clean all packages
melos clean

# Clear pub cache
flutter pub cache clean

# Re-run bootstrap
melos bootstrap --no-select

Flutter version mismatch

Problem: Project requires different Flutter version.

Solution:

# Check required version
cat .fvmrc

# Install FVM
dart pub global activate fvm

# Use project Flutter version
fvm install
fvm use

Code generation not working

Problem: build_runner fails to generate code.

Solution:

# Clean generated files
melos run clean:all

# Re-run generation
melos run generate --no-select

# If still failing, run for specific package
cd packages/[package_name]
flutter pub run build_runner build --delete-conflicting-outputs

API & Backend Issues

Supabase

Connection Issues

Check Supabase Status:

# Local development
supabase status

# Restart if needed
supabase stop
supabase start

Environment Variables:

# Verify .env file
cat .env.development

# Required variables
SUPABASE_URL=your_project_url
SUPABASE_ANON_KEY=your_anon_key

Gemini AI

API Key Issues

Invalid API Key:

• Verify key in Google AI Studio
• Check rate limits
• Ensure correct project

Rate Limiting:

// Implement exponential backoff
int retries = 0;
while (retries < 3) {
  try {
    return await geminiApi.call();
  } catch (e) {
    await Future.delayed(
      Duration(seconds: pow(2, retries))
    );
    retries++;
  }
}

MapBox

Map Loading Issues

Token Configuration:

# Add to .env
MAPBOX_ACCESS_TOKEN=your_token

# iOS: Info.plist
<key>MBXAccessToken</key>
<string>your_token</string>

# Android: strings.xml
<string name="mapbox_access_token">your_token</string>

Build & Deployment

Always test builds locally before pushing to CI/CD.

Android Build Issues

# Clean build
cd android
./gradlew clean
cd ..

# Rebuild
flutter build apk --release

# If Java version issues
export JAVA_HOME=/path/to/java11

iOS Build Issues

# Clean build folder
cd ios
rm -rf Pods Podfile.lock
pod install --repo-update
cd ..

# Rebuild
flutter build ios --release

# Code signing issues
open ios/Runner.xcworkspace
# Fix in Xcode: Signing & Capabilities

Web Build Issues

# Clear web cache
flutter clean
rm -rf build/web

# Rebuild with renderer
flutter build web --web-renderer canvaskit

# For better compatibility
flutter build web --web-renderer html

Debug Techniques

Logging & Debugging

Enhanced Logging

import 'package:logger/logger.dart';

final logger = Logger(
  printer: PrettyPrinter(
    methodCount: 2,
    errorMethodCount: 8,
    lineLength: 120,
    colors: true,
    printEmojis: true,
  ),
);

// Usage
logger.d('Debug message');
logger.e('Error message', error, stackTrace);

Performance Profiling

# Run in profile mode
flutter run --profile

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

Getting Help

Support Channels

1. GitHub Issues: Report bugs
2. Discord Community: Join for real-time help
3. Documentation: Check docs.remind.tools
4. Email Support: [e-mail]

Providing Useful Bug Reports

Include these details for faster resolution:

### Environment
- Flutter version: [flutter --version]
- Platform: [iOS/Android/Web/Desktop]
- Device: [Model and OS version]
- App version: [From pubspec.yaml]

### Steps to Reproduce
1. Step one
2. Step two
3. Step three

### Expected Behavior
What should happen

### Actual Behavior
What actually happens

### Logs/Screenshots
[Attach relevant logs or screenshots]

Emergency Procedures

Data Recovery

# Backup current state
supabase db dump > backup_$(date +%Y%m%d).sql

# Restore from backup
supabase db restore < backup_20240101.sql

Rollback Deployment

# Revert to previous version
git revert HEAD
git push origin main

# Or checkout previous tag
git checkout v1.0.0
git tag v1.0.1
git push origin v1.0.1