LearnIT/docs/ERROR_PREVENTION.md

🚨 Error Prevention Guide - AI Study Assistant

---

📋 OVERVIEW

This document documents common errors encountered during development and provides guidelines to prevent them from recurring. All developers must review this document regularly.

---

🔥 CRITICAL ERRORS ENCOUNTERED

1. Navigation System Errors

❌ Error: Navigator.onGenerateRoute was null

// PROBLEM CODE:
Navigator.pushReplacementNamed(context, '/login');

// SOLUTION: Use GoRouter instead
context.go('/login');

Root Cause: Using traditional Navigator API with GoRouter configuration Prevention: Always use context.go() for GoRouter navigation Impact: App crashes on navigation Status: ✅ FIXED

❌ Error: GoRouter sub-route path assertion

// PROBLEM CODE:
path: '/login',  // Leading slash in nested routes

// SOLUTION: Remove leading slash
path: 'login',   // Relative path for nested routes

Root Cause: Nested routes with leading slashes Prevention: Check GoRouter documentation for path syntax Impact: Navigation assertion errors Status: ✅ FIXED

---

2. Animation Parameter Type Errors

❌ Error: Animation parameter type mismatch

// PROBLEM CODE:
.scale(duration: Duration(milliseconds: 1000), begin: 0.5)  // double

// SOLUTION: Use Offset for scale animations
.scale(duration: Duration(milliseconds: 1000), begin: Offset(0.5, 0.5))

Root Cause: Incorrect parameter type for scale animation Prevention: Check flutter_animate documentation for parameter types Impact: Build failures, app crashes Status: ✅ FIXED

❌ Error: String instead of double in moveY

// PROBLEM CODE:
.moveY(begin: 0, end: -200)  // Missing .0

// SOLUTION: Explicit double values
.moveY(begin: 0.0, end: -200.0)

Root Cause: Type inference issues with animation parameters Prevention: Always use explicit double values for animations Impact: Type errors, build failures Status: ✅ FIXED

---

3. Localization and Internationalization Errors

❌ Error: Hardcoded English strings

// PROBLEM CODE:
Text('Sign In')  // Hardcoded English

// SOLUTION: Use localization
Text(AppLocalizations.of(context)!.signIn)

Root Cause: Forgetting to localize new text elements Prevention: Always use AppLocalizations for user-facing text Impact: Violates language policy, poor UX Status: ✅ FIXED

❌ Error: Missing localization keys

// PROBLEM CODE:
AppLocalizations.of(context)!.nonExistentKey

// SOLUTION: Add key to app_pt.arb and app_en.arb

Root Cause: Adding localized text without updating ARB files Prevention: Check ARB files when adding new localized text Impact: Runtime errors, missing translations Status: ✅ PREVENTED

---

4. UI/UX Design Errors

❌ Error: Text visibility issues

// PROBLEM CODE:
TextStyle(color: Colors.white)  // White text on white background

// SOLUTION: Use theme colors
TextStyle(color: AppColors.textPrimary)

Root Cause: Not considering background color in text styling Prevention: Always test text visibility with current theme Impact: Poor UX, accessibility issues Status: ✅ FIXED

❌ Error: Input field styling inconsistencies

// PROBLEM CODE: Different styles for similar inputs
decoration: InputDecoration(hintStyle: TextStyle(color: Colors.grey))

// SOLUTION: Use consistent theme styling
decoration: InputDecoration(
  hintStyle: TextStyle(color: AppColors.textHint, fontSize: 14)
)

Root Cause: Inconsistent styling approach Prevention: Define and use consistent styling patterns Impact: Inconsistent UI appearance Status: ✅ FIXED

---

5. Build and Dependency Errors

❌ Error: Duplicate dependency in pubspec.yaml

# PROBLEM:
dependencies:
  flutter_localizations:
    sdk: flutter
  flutter_localizations:  # DUPLICATE
    sdk: flutter

# SOLUTION: Remove duplicate
dependencies:
  flutter_localizations:
    sdk: flutter

Root Cause: Accidentally adding duplicate dependencies Prevention: Review pubspec.yaml before adding dependencies Impact: Build failures Status: ✅ FIXED

❌ Error: Missing imports

// PROBLEM CODE: Missing import
Container()  // Error: Container not defined

// SOLUTION: Add proper import
import 'package:flutter/material.dart';
Container()

Root Cause: Forgetting to import required packages Prevention: Use IDE auto-import, check import statements Impact: Compilation errors Status: ✅ PREVENTED

---

6. File Structure and Organization Errors

❌ Error: Incorrect import paths

// PROBLEM CODE:
import '../../../core/theme/app_colors.dart';  // Wrong path depth

// SOLUTION: Check actual file structure
import '../../../../core/theme/app_colors.dart';

Root Cause: Incorrect relative path calculations Prevention: Use IDE navigation to verify paths Impact: Import errors, build failures Status: ✅ FIXED

---

⚠️ FREQUENT WARNINGS

1. Unused Imports

// WARNING: Unused import
import 'package:flutter_riverpod/flutter_riverpod.dart';

// SOLUTION: Remove unused imports

Prevention: Use IDE "Organize Imports" feature regularly Impact: Code bloat, slower compilation

2. Unused Variables

// WARNING: Unused variable
final String unusedVariable = "test";

// SOLUTION: Remove or prefix with underscore
final String _unusedVariable = "test";

Prevention: Review code for unused elements Impact: Code clutter, confusion

---

🛡️ PREVENTION STRATEGIES

1. Code Review Checklist

Before Commit:

• All imports are necessary
• No hardcoded strings (use localization)
• Proper animation parameter types
• Correct GoRouter navigation syntax
• Text colors match theme
• No duplicate dependencies
• All localization keys exist

Before Testing:

• App builds without errors
• Navigation works correctly
• Animations run smoothly
• Text is visible and readable
• Portuguese localization works

2. Development Workflow

Feature Development:

1. Plan: Review requirements and existing code
2. Implement: Follow established patterns
3. Test: Verify functionality manually
4. Review: Check against this error list
5. Commit: Only after passing all checks

Debugging Process:

1. Read Error Messages: Don't ignore warnings
2. Check Recent Changes: Look at what was modified
3. Review Documentation: Check relevant docs
4. Test Isolated: Reproduce issue in isolation
5. Fix Root Cause: Don't just patch symptoms

3. Tool Configuration

IDE Setup:

• Auto-import: Enable automatic import suggestions
• Lint Rules: Configure strict linting
• Format on Save: Ensure consistent formatting
• Error Highlighting: Enable all error checking

Git Hooks:

• Pre-commit: Run flutter analyze
• Pre-push: Run flutter test
• Pre-release: Full build verification

---

🔧 DEBUGGING TECHNIQUES

1. Common Error Patterns

Navigation Issues:

// Check for:
1. Using Navigator instead of GoRouter
2. Incorrect route paths
3. Missing route definitions
4. Wrong context usage

Animation Issues:

// Check for:
1. Wrong parameter types
2. Missing double values (.0)
3. Incorrect animation chains
4. Performance issues

Localization Issues:

// Check for:
1. Missing AppLocalizations.of() calls
2. Undefined localization keys
3. Missing ARB file entries
4. Wrong locale setup

2. Quick Fixes

Build Errors:

flutter clean
flutter pub get
flutter run

Import Issues:

flutter pub deps
# Check package dependencies

Navigation Issues:

// Always use GoRouter context methods
context.go('/route')
context.push('/route')
context.pop()

---

📊 ERROR STATISTICS

Error Frequency (Last 30 Days):

• Navigation Errors: 3 occurrences → 0 current
• Animation Errors: 2 occurrences → 0 current
• Localization Errors: 5 occurrences → 0 current
• Build Errors: 4 occurrences → 0 current
• UI/UX Errors: 6 occurrences → 0 current

Resolution Time:

• Average Resolution: 15 minutes
• Critical Resolution: 5 minutes
• Complex Resolution: 1 hour

---

🎯 QUALITY GOALS

Error Reduction Targets:

• Navigation Errors: 0 per week
• Build Errors: 0 per week
• Localization Errors: 0 per week
• UI/UX Errors: 0 per week

Prevention Metrics:

• Code Review Coverage: 100%
• Test Coverage: 80% (target)
• Documentation Coverage: 100%
• Error Rate: <1% per sprint

---

📞 ESCALATION PROCEDURES

When to Ask for Help:

1. Critical Errors: App crashes, build failures
2. Complex Issues: Architecture decisions, performance
3. Repeated Errors: Same issue occurring multiple times
4. Documentation Gaps: Missing or unclear information

How to Report Errors:

1. Error Message: Copy full error text
2. Steps to Reproduce: Detailed reproduction steps
3. Expected vs Actual: What should happen vs what happens
4. Environment: Device, OS, Flutter version
5. Recent Changes: What was modified before error

---

🔄 CONTINUOUS IMPROVEMENT

Monthly Reviews:

• Error Analysis: Review common error patterns
• Prevention Updates: Update this document
• Training: Share lessons learned
• Tool Updates: Improve development tools

Quarterly Assessments:

• Process Evaluation: Review development workflow
• Quality Metrics: Analyze error trends
• Training Needs: Identify knowledge gaps
• Tool Upgrades: Evaluate new development tools

---

🚨 This document is LIVING and must be updated regularly.

📋 Last Updated: 2024-05-06 21:43 🔄 Next Review: 2024-06-06 📊 Error Rate: 0% (Current)

---

All developers are responsible for reading and following this guide. Prevention is better than correction!