> ## 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.

# Common Issues

> Solutions for frequently encountered problems

# Common Issues & Solutions

Quick solutions for the most frequently encountered problems in Remind Tools development.

## Development Issues

### Melos Bootstrap Failures

<AccordionGroup>
  <Accordion title="Dependency conflicts">
    **Error**: `Because X depends on Y version...`

    **Solution**:

    ```bash theme={null}
    # Clear all caches
    melos clean
    flutter pub cache clean

    # Remove lock files
    find . -name "pubspec.lock" -delete

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

  <Accordion title="Package not found">
    **Error**: `Could not find package X`

    **Solution**:

    ```bash theme={null}
    # Update pub cache
    flutter pub cache repair

    # If private package
    cd packages/[package_name]
    flutter pub get
    cd ../..
    melos bootstrap
    ```
  </Accordion>

  <Accordion title="Version solving failed">
    **Error**: `Version solving failed`

    **Solution**:

    ```bash theme={null}
    # Use dependency override in pubspec.yaml
    dependency_overrides:
      package_name: ^version

    # Then bootstrap
    melos bootstrap
    ```
  </Accordion>
</AccordionGroup>

### Build Failures

<Tabs>
  <Tab title="iOS">
    ### Common iOS Issues

    **CocoaPods Issues**

    ```bash theme={null}
    cd ios
    pod cache clean --all
    rm -rf Pods Podfile.lock
    pod install --repo-update
    ```

    **Signing Issues**

    ```bash theme={null}
    # Open in Xcode
    open ios/Runner.xcworkspace
    # Fix in: Signing & Capabilities
    ```

    **Build Clean**

    ```bash theme={null}
    flutter clean
    cd ios
    xcodebuild clean
    cd ..
    flutter build ios
    ```
  </Tab>

  <Tab title="Android">
    ### Common Android Issues

    **Gradle Issues**

    ```bash theme={null}
    cd android
    ./gradlew clean
    ./gradlew --stop
    cd ..
    flutter build apk
    ```

    **JDK Version**

    ```bash theme={null}
    # Check Java version
    java -version

    # Set JAVA_HOME
    export JAVA_HOME=/path/to/jdk11
    ```

    **Build Cache**

    ```bash theme={null}
    rm -rf ~/.gradle/caches
    cd android
    ./gradlew clean build
    ```
  </Tab>

  <Tab title="Web">
    ### Common Web Issues

    **Renderer Issues**

    ```bash theme={null}
    # Try different renderer
    flutter build web --web-renderer html
    # or
    flutter build web --web-renderer canvaskit
    ```

    **Cache Issues**

    ```bash theme={null}
    flutter clean
    rm -rf build/web
    flutter build web
    ```
  </Tab>
</Tabs>

## Runtime Issues

### State Management

<Warning>
  Always dispose of controllers and subscriptions to prevent memory leaks.
</Warning>

```dart theme={null}
// BLoC disposal
@override
void dispose() {
  _bloc.close();
  super.dispose();
}

// Riverpod disposal
ref.onDispose(() {
  controller.dispose();
});
```

### Performance Issues

| Problem         | Solution                                     |
| --------------- | -------------------------------------------- |
| Janky scrolling | Use `ListView.builder` instead of `ListView` |
| Slow navigation | Preload routes with `precacheImage`          |
| Memory leaks    | Check for disposed controllers               |
| Large images    | Use `cached_network_image` package           |

## API Issues

### Supabase Connection

```dart theme={null}
// Check connection
if (!supabase.auth.currentSession) {
  // Re-authenticate
  await supabase.auth.refreshSession();
}

// Handle errors
try {
  final data = await supabase.from('table').select();
} on PostgrestException catch (e) {
  print('Database error: ${e.message}');
} catch (e) {
  print('Network error: $e');
}
```

### Rate Limiting

```dart theme={null}
class RateLimitHandler {
  static Future<T> withRetry<T>(
    Future<T> Function() operation,
  ) async {
    int retries = 0;
    while (retries < 3) {
      try {
        return await operation();
      } on RateLimitException {
        await Future.delayed(
          Duration(seconds: math.pow(2, retries).toInt()),
        );
        retries++;
      }
    }
    throw Exception('Max retries exceeded');
  }
}
```

## Testing Issues

### Test Failures

<AccordionGroup>
  <Accordion title="Golden test mismatches">
    ```bash theme={null}
    # Update golden files
    flutter test --update-goldens

    # Platform-specific goldens
    flutter test --update-goldens --platform=ios
    ```
  </Accordion>

  <Accordion title="Widget test timeouts">
    ```dart theme={null}
    testWidgets('test', (tester) async {
      // Increase timeout
      tester.binding.addTime(Duration(seconds: 30));
      
      // Or use longer timeout
    }, timeout: Timeout(Duration(minutes: 2)));
    ```
  </Accordion>

  <Accordion title="Integration test issues">
    ```bash theme={null}
    # Run on specific device
    flutter test integration_test/app_test.dart \
      -d "iPhone 14"

    # With driver
    flutter drive \
      --driver=test_driver/integration_test.dart \
      --target=integration_test/app_test.dart
    ```
  </Accordion>
</AccordionGroup>

## Quick Fixes

### Reset Everything

```bash theme={null}
#!/bin/bash
# Complete reset script

echo "Cleaning Flutter..."
flutter clean

echo "Cleaning Melos..."
melos clean

echo "Clearing caches..."
flutter pub cache clean

echo "Removing lock files..."
find . -name "pubspec.lock" -delete
find . -name ".packages" -delete
find . -name ".dart_tool" -type d -exec rm -rf {} +

echo "Re-installing dependencies..."
melos bootstrap

echo "Running code generation..."
melos run generate

echo "Reset complete!"
```

### Emergency Contacts

* **GitHub Issues**: [Report bugs](https://github.com/design4pro/remind_tools/issues)
* **Discord**: [Community support](https://discord.gg/remind-tools)
* **Email**: [support@remind.tools](mailto:support@remind.tools)