> ## Documentation Index
> Fetch the complete documentation index at: https://docs.remind.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CardGroup cols={2}>
  <Card title="Common Issues" icon="triangle-exclamation" href="/troubleshooting/common-issues">
    General problems and their solutions
  </Card>

  <Card title="Platform Specific" icon="laptop-mobile" href="/troubleshooting/platform-specific">
    iOS, Android, Web, and Desktop issues
  </Card>
</CardGroup>

## Frequently Encountered Issues

### Development Environment

<AccordionGroup>
  <Accordion title="Melos bootstrap fails">
    **Problem**: `melos bootstrap` command fails with dependency errors.

    **Solution**:

    ```bash theme={null}
    # Clean all packages
    melos clean

    # Clear pub cache
    flutter pub cache clean

    # Re-run bootstrap
    melos bootstrap --no-select
    ```
  </Accordion>

  <Accordion title="Flutter version mismatch">
    **Problem**: Project requires different Flutter version.

    **Solution**:

    ```bash theme={null}
    # Check required version
    cat .fvmrc

    # Install FVM
    dart pub global activate fvm

    # Use project Flutter version
    fvm install
    fvm use
    ```
  </Accordion>

  <Accordion title="Code generation not working">
    **Problem**: `build_runner` fails to generate code.

    **Solution**:

    ```bash theme={null}
    # 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
    ```
  </Accordion>
</AccordionGroup>

### API & Backend Issues

<Tabs>
  <Tab title="Supabase">
    ### Connection Issues

    **Check Supabase Status**:

    ```bash theme={null}
    # Local development
    supabase status

    # Restart if needed
    supabase stop
    supabase start
    ```

    **Environment Variables**:

    ```bash theme={null}
    # Verify .env file
    cat .env.development

    # Required variables
    SUPABASE_URL=your_project_url
    SUPABASE_ANON_KEY=your_anon_key
    ```
  </Tab>

  <Tab title="Gemini AI">
    ### API Key Issues

    **Invalid API Key**:

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

    **Rate Limiting**:

    ```dart theme={null}
    // 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++;
      }
    }
    ```
  </Tab>

  <Tab title="MapBox">
    ### Map Loading Issues

    **Token Configuration**:

    ```bash theme={null}
    # 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>
    ```
  </Tab>
</Tabs>

### Build & Deployment

<Warning>
  Always test builds locally before pushing to CI/CD.
</Warning>

#### Android Build Issues

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

<CodeGroup>
  ```dart title="Enhanced Logging" theme={null}
  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);
  ```

  ```dart title="Network Debugging" theme={null}
  // Enable network logging
  Dio dio = Dio()
    ..interceptors.add(
      LogInterceptor(
        request: true,
        requestHeader: true,
        requestBody: true,
        responseHeader: true,
        responseBody: true,
      ),
    );
  ```
</CodeGroup>

### Performance Profiling

```bash theme={null}
# 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](https://github.com/design4pro/remind_tools/issues)
2. **Discord Community**: Join for real-time help
3. **Documentation**: Check [docs.remind.tools](https://docs.remind.tools)
4. **Email Support**: [support@remind.tools](mailto:support@remind.tools)

### Providing Useful Bug Reports

<Tip>
  Include these details for faster resolution:
</Tip>

```markdown theme={null}
### 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

```bash theme={null}
# Backup current state
supabase db dump > backup_$(date +%Y%m%d).sql

# Restore from backup
supabase db restore < backup_20240101.sql
```

### Rollback Deployment

```bash theme={null}
# 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
```