Troubleshooting

Build & Compilation Issues

Build fails with 'Gradle sync failed' on Android

Symptom: Android build fails with Gradle configuration errors.Common Causes:

AGP (Android Gradle Plugin) version incompatibility
Java version mismatch
Cached build artifacts

Solutions:

Clean the build cache:

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

Check AGP version in android/build.gradle:

buildscript {
  dependencies {
    classpath 'com.android.tools.build:gradle:8.1.0' // AGP 8+
  }
}

Ensure Java 17 is installed:
```
java -version  # Should show Java 17+
```

Update Gradle wrapper:

cd android
./gradlew wrapper --gradle-version=8.3

Note: Vitu requires AGP 8+ due to removal of activity_recognition_flutter.

iOS build fails with CocoaPods errors

Symptom: pod install fails or iOS build errors related to dependencies.Solutions:

Update CocoaPods:

sudo gem install cocoapods
pod --version  # Should be 1.11+

Clean and reinstall pods:

cd ios
rm -rf Pods Podfile.lock
pod install --repo-update
cd ..
flutter clean
flutter build ios

Check Xcode version:
```
xcodebuild -version  # Should be 14.0+
```
Set deployment target in ios/Podfile:
```
platform :ios, '12.0'
```

Flutter SDK version mismatch

Symptom: “The current Dart SDK version is X.X.X” but requires ^3.10.8.Solutions:

Check Flutter version:
```
flutter --version
```
Update Flutter:
```
flutter upgrade
flutter doctor
```
Switch Flutter channel (if needed):
```
flutter channel stable
flutter upgrade
```
Verify Dart SDK:
```
dart --version  # Should be 3.10.8+
```

Package version conflicts

Symptom: “version solving failed” during flutter pub get.Solutions:

Run pub get with verbose output:
```
flutter pub get --verbose
```
Check for conflicting dependencies:
```
flutter pub outdated
```

Update specific package:

flutter pub upgrade google_generative_ai

Clear pub cache:
```
flutter pub cache repair
```

Known Issues:

google_generative_ai downgraded from ^0.5.0 to ^0.4.0 for stability
screen_state pinned to exact version 5.0.0

Permission Errors

Camera permission denied on Android

Symptom: App crashes or shows error when attempting to take photos.Solutions:

Add permissions to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

Request runtime permissions (Android 6+):

final ImagePicker picker = ImagePicker();
final XFile? image = await picker.pickImage(
  source: ImageSource.camera,
);
// Permission request is automatic with image_picker

Check app settings:
- Settings → Apps → Vitu → Permissions → Camera → Allow
Test on different Android versions:
- Android 6-10: Runtime permissions
- Android 11+: Scoped storage

Location permission denied

Symptom: Exercise tracking doesn’t work, speed shows 0.0 km/h.Solutions:

Android: Add to AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

iOS: Add to Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Track your activity and calculate speed</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Track activity in background</string>

Runtime request (lib/main.dart:1739-1769):

LocationPermission perm = await Geolocator.checkPermission();
if (perm == LocationPermission.denied) {
  perm = await Geolocator.requestPermission();
}
if (perm == LocationPermission.deniedForever) {
  // Show dialog to open settings
  await Geolocator.openLocationSettings();
}

Enable location services:
- Android: Settings → Location → On
- iOS: Settings → Privacy → Location Services → On

Sensor access errors

Symptom: Step counting doesn’t work, accelerometer data unavailable.Solutions:

Check sensor availability:

_accelSub = userAccelerometerEventStream().listen(
  (event) {
    print('Accel: ${event.x}, ${event.y}, ${event.z}');
  },
  onError: (e) {
    print('Sensor error: $e');
  },
);

Android: Add to AndroidManifest.xml:

<uses-feature android:name="android.hardware.sensor.accelerometer" />
<uses-feature android:name="android.hardware.sensor.gyroscope" />

Test on physical device: Sensors don’t work on most emulators
Calibrate sensors: Settings → System → Sensors (device-specific)

Photo library access denied on iOS

Symptom: Cannot select photos from gallery on iOS.Solutions:

Add to ios/Runner/Info.plist:

<key>NSPhotoLibraryUsageDescription</key>
<string>Select food photos for nutritional analysis</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Save analyzed food photos</string>

Check iOS version compatibility:
- iOS 14+: Limited photos access
- iOS 11-13: Full library access
Reset permissions (for testing):
- Settings → General → Reset → Reset Location & Privacy

Gemini API Issues

Gemini API key invalid or expired

Symptom: “API key not valid” or 401 Unauthorized errors.Solutions:

Generate new API key:
- Visit: https://aistudio.google.com/app/apikey
- Create new key or regenerate existing
- Copy to clipboard

Update in code (lib/main.dart:489):

const apiKey = 'YOUR_NEW_API_KEY_HERE';
_geminiModel = GenerativeModel(
  model: 'gemini-2.5-flash',
  apiKey: apiKey,
);

Use environment variables (recommended):

final apiKey = const String.fromEnvironment(
  'GEMINI_API_KEY',
  defaultValue: 'fallback_key',
);

Run with:

flutter run --dart-define=GEMINI_API_KEY=your_key_here

Verify key restrictions:
- Check API key hasn’t been restricted by IP/domain
- Ensure Generative Language API is enabled

Rate limit exceeded

Symptom: “429 Too Many Requests” or “Quota exceeded” errors.Limits (Free Tier):

60 requests per minute
1,500 requests per day
1 million tokens per day

Solutions:

Implement request throttling:

DateTime? _lastRequest;
Future<void> _analizarConGemini(File foto) async {
  final now = DateTime.now();
  if (_lastRequest != null) {
    final diff = now.difference(_lastRequest!);
    if (diff.inSeconds < 2) {
      await Future.delayed(Duration(seconds: 2 - diff.inSeconds));
    }
  }
  _lastRequest = now;
  // Make API call...
}

Cache responses:
- Store recent analyses in Hive
- Avoid re-analyzing same image
Upgrade to paid tier: https://ai.google.dev/pricing
Monitor usage: Check quota in Google Cloud Console

Gemini returns empty or invalid response

Symptom: resp.text is null or doesn’t match expected format.Solutions:

Check prompt format (lib/main.dart:646-658):

final prompt = '''
Analyze this food photo.
Identify the main dish.
Estimate nutritional values.
Respond ONLY in this exact format, no additional text:
Plato: [approximate name]
Calorías: [number] kcal
Proteínas: [number] g
Carbohidratos: [number] g
Grasas: [number] g
''';

Add response validation:

final text = resp.text ?? '';
debugPrint('Gemini raw response:\n$text');
if (text.isEmpty) {
  throw Exception('Empty response from Gemini');
}

Handle parsing errors (lib/main.dart:681-711):

final platoMatch = RegExp(
  r'^Plato:\s*(.+)$',
  multiLine: true,
  caseSensitive: false,
).firstMatch(text);

if (platoMatch == null) {
  print('Failed to parse dish name');
  // Fallback or retry
}

Verify model name:
- Use gemini-2.5-flash (latest)
- Fallback to gemini-pro-vision if needed

Image too large for Gemini API

Symptom: “Request payload too large” or timeout errors.Image Limits:

Max file size: 4MB (recommended < 2MB)
Supported formats: JPEG, PNG, WebP
Max dimensions: 3000x3000px

Solutions:

Compress image (lib/main.dart:536-539):

final XFile? xfile = await picker.pickImage(
  source: source,
  imageQuality: 85,  // Reduce to 70-80 for larger images
  maxWidth: 1920,
  maxHeight: 1920,
);

Check file size before upload:

final bytes = await foto.readAsBytes();
final length = bytes.length;
if (length > 2 * 1024 * 1024) {  // 2MB
  throw Exception('Image too large: ${length ~/ 1024}KB');
}

Use image compression package:

dependencies:
  image: ^4.0.0

import 'package:image/image.dart' as img;

final image = img.decodeImage(await foto.readAsBytes());
final resized = img.copyResize(image!, width: 1024);
final compressed = img.encodeJpg(resized, quality: 85);

Network connectivity issues

Symptom: SocketException or “No internet connection” errors.Solutions:

Check internet connectivity:

import 'dart:io';

Future<bool> hasNetwork() async {
  try {
    final result = await InternetAddress.lookup('google.com');
    return result.isNotEmpty && result[0].rawAddress.isNotEmpty;
  } catch (_) {
    return false;
  }
}

Add timeout to requests (lib/main.dart:665-666):

final resp = await _geminiModel
  .generateContent([content])
  .timeout(const Duration(seconds: 20));

Implement retry logic:

int retries = 3;
while (retries > 0) {
  try {
    final resp = await _geminiModel.generateContent([content]);
    return resp;
  } catch (e) {
    retries--;
    if (retries == 0) rethrow;
    await Future.delayed(Duration(seconds: 2));
  }
}

Add error UI (lib/main.dart:614-627):

_showSnack(
  'No internet connection',
  error: true,
  onRetry: () {
    if (_photo != null) _analizarConGemini(_photo!);
  },
);

Data & Storage Issues

Hive box not opened or corrupted

Symptom: “Box not found” or “Failed to open box” errors.Solutions:

Ensure boxes are opened (lib/main.dart:23-28):

await Hive.initFlutter();
await Hive.openBox('users');
await Hive.openBox('user_settings');
await Hive.openBox('daily_exercise');
await Hive.openBox('hydration_logs');
await Hive.openBox('daily_hydration_summary');

Delete corrupted box:

await Hive.deleteBoxFromDisk('corrupted_box_name');
await Hive.openBox('corrupted_box_name');

Clear all Hive data (for testing):

await Hive.close();
final dir = await getApplicationDocumentsDirectory();
final hivePath = '${dir.path}/hive';
final hiveDir = Directory(hivePath);
if (await hiveDir.exists()) {
  await hiveDir.delete(recursive: true);
}
await Hive.initFlutter();
// Re-open boxes

Check box names match:

Box get _usersBox => Hive.box('users');  // Must match opened name

User data not persisting

Symptom: Login state lost after app restart, settings reset.Solutions:

Verify save operations (lib/main.dart:150-153):

Future<void> saveCurrentUser(User u) async {
  await _usersBox.put('user:${u.correo}', u.toMap());
  await _usersBox.put('currentUserEmail', u.correo);
  print('User saved: ${u.correo}');
}

Check key format:

// Consistent key format
final key = 'user:${email.trim().toLowerCase()}';
final data = _usersBox.get(key);

Flush data manually:

await _usersBox.put(key, value);
await _usersBox.flush();  // Force write to disk

Debug stored data:

print('All users box keys: ${_usersBox.keys}');
print('Current user: ${getCurrentUserEmail()}');

Exercise/hydration data not showing

Symptom: Weekly charts empty, step counts reset to zero.Solutions:

Verify date key format (lib/main.dart:221-222):

String _dateKey(DateTime d) =>
  '${d.year.toString().padLeft(4, '0')}-${d.month.toString().padLeft(2, '0')}-${d.day.toString().padLeft(2, '0')}';

Check composite keys:

final userId = getCurrentUserEmail();
final today = _dateKey(DateTime.now());
final key = '${userId}_$today';
print('Looking for data at key: $key');

Inspect box contents:

final allKeys = _dailyExerciseBox.keys.toList();
print('Exercise box keys: $allKeys');
for (final key in allKeys) {
  print('$key: ${_dailyExerciseBox.get(key)}');
}

Verify data structure:

final raw = _dailyExerciseBox.get(key);
if (raw is Map) {
  print('Steps: ${raw['steps']}');
  print('Date: ${raw['date']}');
} else {
  print('Invalid data type: ${raw.runtimeType}');
}

Platform-Specific Issues

Android build fails with 'MultiDex' error

Symptom: Build fails with “Cannot fit requested classes in a single dex file”.Solutions:

Enable MultiDex in android/app/build.gradle:

android {
  defaultConfig {
    multiDexEnabled true
  }
}

dependencies {
  implementation 'androidx.multidex:multidex:2.0.1'
}

Update Application class (if custom):

import androidx.multidex.MultiDexApplication

class MyApp : MultiDexApplication() {
  // ...
}

iOS app crashes on launch

Symptom: App immediately crashes after launch on iOS.Solutions:

Check Xcode console for error:
```
flutter run --verbose
```
Verify Info.plist is valid XML:
```
plutil -lint ios/Runner/Info.plist
```

Clean derived data:

cd ios
rm -rf ~/Library/Developer/Xcode/DerivedData
flutter clean
pod install

Check minimum iOS version:
- Vitu requires iOS 12.0+
- Update in ios/Podfile if needed

Web build size too large

Symptom: Web build is slow to load, large bundle size.Solutions:

Build in release mode:
```
flutter build web --release
```

Enable tree shaking:

flutter build web --release --tree-shake-icons

Split deferred loading (advanced):

import 'heavy_screen.dart' deferred as heavy;

// Later:
await heavy.loadLibrary();
Navigator.push(/* ... */);

Runtime Errors

'setState() called after dispose()' error

Symptom: Unhandled exception when updating state after navigation.Solutions:

Check mounted before setState:

if (mounted) {
  setState(() {
    // Update state
  });
}

Cancel async operations in dispose:

@override
void dispose() {
  _accelSub?.cancel();
  _posSub?.cancel();
  _timer?.cancel();
  super.dispose();
}

Use State lifecycle properly:

Future<void> loadData() async {
  final data = await fetchData();
  if (!mounted) return;  // Exit if widget disposed
  setState(() => _data = data);
}

Memory leaks / app slowdown over time

Symptom: App becomes sluggish after extended use, high memory usage.Solutions:

Dispose controllers properly:

late final AnimationController _controller;

@override
void dispose() {
  _controller.dispose();
  super.dispose();
}

Cancel stream subscriptions:

StreamSubscription? _sub;

@override
void dispose() {
  _sub?.cancel();
  super.dispose();
}

Use DevTools to profile:

flutter run --profile
# Open DevTools → Memory → Take snapshot

Limit list growth (lib/main.dart:1796-1802):

if (_cardioSpots.length > 60) {
  _cardioSpots.removeAt(0);  // Keep only recent data
}

Debugging Tips

Enable Verbose Logging

flutter run --verbose

Check Logs by Platform

Android:

adb logcat | grep flutter

iOS:

flutter logs

All platforms:

import 'package:flutter/foundation.dart';

if (kDebugMode) {
  debugPrint('Debug info: $variable');
}

Use Flutter DevTools

flutter pub global activate devtools
flutter pub global run devtools

Features:

Widget Inspector
Memory Profiler
Performance Timeline
Network Monitor

Getting Help

Resources

Flutter Docs: https://docs.flutter.dev
Gemini AI Docs: https://ai.google.dev/docs
Hive Docs: https://docs.hivedb.dev
Stack Overflow: https://stackoverflow.com/questions/tagged/flutter

Reporting Issues

When reporting bugs, include:

Flutter version (flutter --version)
Platform and OS version
Full error stack trace
Steps to reproduce
Expected vs actual behavior

Debug Checklist

Run flutter doctor and fix all issues
Check all permissions are granted
Verify API keys are valid
Test on physical device (not just emulator)
Check network connectivity
Review logs for error messages
Try flutter clean && flutter pub get
Update to latest stable Flutter version

Resources

Best Practices

Troubleshooting

Build & Compilation Issues

Permission Errors

Gemini API Issues

Data & Storage Issues

Platform-Specific Issues

Runtime Errors

Debugging Tips

Enable Verbose Logging

Check Logs by Platform

Use Flutter DevTools

Getting Help

Resources

Reporting Issues

Debug Checklist

Build docs developers (and LLMs) love

Resources

Best Practices

​Build & Compilation Issues

​Permission Errors

​Gemini API Issues

​Data & Storage Issues

​Platform-Specific Issues

​Runtime Errors

​Debugging Tips

​Enable Verbose Logging

​Check Logs by Platform

​Use Flutter DevTools

​Getting Help

​Resources

​Reporting Issues

​Debug Checklist

Build docs developers (and LLMs) love

Build & Compilation Issues

Permission Errors

Gemini API Issues

Data & Storage Issues

Platform-Specific Issues

Runtime Errors

Debugging Tips

Enable Verbose Logging

Check Logs by Platform

Use Flutter DevTools

Getting Help

Resources

Reporting Issues

Debug Checklist