Cross-Reference: This help system is fully integrated with AI_TROUBLESHOOTING_FRAMEWORK.md - the Quaex Industrial Platform methodology
# Run this first to identify the category (Quaex platform specific):
./docs/scripts/quick_diagnosis.sh
Problem Categories & Quick Access (Industrial Platform):
Because package_name requires SDK version >=X.Y.Z, version solving failed
The current Dart SDK version is A.B.C
# 1. Quick diagnosis
flutter pub deps | grep -A 5 -B 5 "package_name"
# 2. Find compatible version
flutter pub downgrade package_name
# 3. Manual downgrade (recommended)
# Edit pubspec.yaml, change from ^X.Y.Z to compatible version
# 4. Validate fix
flutter pub get && flutter analyze && flutter test
# For Dart SDK 3.3.4 (Flutter 3.19.6):
flutter_riverpod: ^2.6.1 # NOT ^3.0.0
go_router: ^14.6.0 # NOT ^16.2.4
mobile_scanner: ^5.1.0 # NOT ^7.1.2
shared_preferences: ^2.2.3 # NOT ^2.3.2
crypto: ^3.0.3 # NOT ^3.0.5
flutter_lints: ^4.0.0 # NOT ^6.0.0
β Framework Reference: Phase 2.1 - Critical Dependency Chains
Compilation failed
Error: The method 'methodName' isn't defined for the class 'ClassName'
Common API Changes in Flutter/Dart:
| Old API | New API | Dart Version | Fix |
|---|---|---|---|
withValues(alpha: 0.4) |
withOpacity(0.4) |
<3.4 | Global replace |
surfaceContainerHighest |
surface |
<3.4 | Property replace |
backgroundColor |
colorScheme.background |
3.0+ | Context update |
# Fix withValues issues (proven solution)
find lib/ -name "*.dart" -exec sed -i 's/withValues(alpha: [0-9.]*)/withOpacity(0.4)/g' {} \;
# Fix surfaceContainerHighest issues
find lib/ -name "*.dart" -exec sed -i 's/surfaceContainerHighest/surface/g' {} \;
# Validate all changes
flutter analyze
flutter test
# Nuclear option - clean everything
flutter clean
rm -rf .dart_tool/ build/ .flutter-plugins .flutter-plugins-dependencies
rm pubspec.lock
flutter pub get
flutter packages upgrade --dry-run # Check what would change
β Framework Reference: Phase 3.1 - Pattern 2: API Compatibility Issues
Expected: findsOneWidget
Actual: findsNothing
Expected to find exactly one widget, but found none
# 1. Identify which tests are failing
flutter test --reporter expanded | grep -E "(FAIL|β)"
# 2. Debug specific test
flutter test test/widget_test.dart --plain-name="test name here"
# 3. Update test expectations based on current UI
After UI changes, update these in test files:
// OLD (might fail):
expect(find.text('Welcome to Karosuru'), findsOneWidget);
expect(find.text('Sign In'), findsOneWidget);
// NEW (structure-based, more reliable):
expect(find.byType(MaterialApp), findsOneWidget);
expect(find.byType(TabBar), findsOneWidget);
expect(find.text('Welcome to Karosuru'), findsOneWidget);
#!/bin/bash
# test_debug.sh
echo "π§ͺ Test Debugging Helper"
echo "Failed tests:"
flutter test --reporter json | jq -r '.[] | select(.type=="testDone" and .result=="error") | .test.name'
echo
echo "Passed tests:"
flutter test --reporter json | jq -r '.[] | select(.type=="testDone" and .result=="success") | .test.name'
β Framework Reference: Phase 5.2 - Test Failure Resolution
Symptom:
fatal: detected dubious ownership in repository at '/workspaces/quaex'
Fix:
git config --global --add safe.directory /workspaces/quaex
git config --global --add safe.directory /opt/flutter # If Flutter issues
Symptom:
bash: flutter: command not found
The SDK configured is not a valid SDK folder
Fix:
# 1. Check current Flutter installation
which flutter
echo $PATH
# 2. Add Flutter to PATH (if needed)
export PATH="$PATH:/usr/local/flutter/bin"
echo 'export PATH="$PATH:/usr/local/flutter/bin"' >> ~/.bashrc
# 3. Validate Flutter setup
flutter doctor
flutter --version
Supabase Configuration Debug:
// Add to main.dart for debugging:
print('SUPABASE_URL: ${dotenv.maybeGet('SURUCEAN_URL')}');
print('PLACEHOLDER_CONFIG: ${SuruceranConfig.isPlaceholderConfig}');
β Framework Reference: Phase 1.3 - Known Issue Patterns
Analysis Commands:
# Profile build time
time flutter build web --debug --verbose
# Check cache size
du -sh .dart_tool/
du -sh build/
# Clean if excessive
flutter clean
flutter pub get
Symptoms:
Solutions:
# 1. Increase VM memory (temporary)
export DART_VM_OPTIONS="--max-heap-size=4096MB"
# 2. Exclude directories from analysis
# Edit analysis_options.yaml:
analyzer:
exclude:
- build/**
- .dart_tool/**
- flutter/**
# 3. Use build caching
flutter build web --dart-define=FLUTTER_WEB_USE_SKIA=true
β Framework Reference: Phase 5.1 - Performance Benchmarks
# Health check (run before starting work)
flutter doctor && flutter analyze && flutter test
# Dependency refresh (weekly)
flutter pub outdated
flutter pub upgrade --dry-run
# Emergency reset (when things break)
flutter clean && rm pubspec.lock && flutter pub get
# Pre-commit validation
flutter analyze --fatal-infos && flutter test && flutter build web --debug
# Detailed dependency analysis
flutter pub deps --json | jq '.packages[] | {name: .name, version: .version, kind: .kind}'
# Find large files impacting build time
find build/ -type f -size +1M -exec ls -lh {} \; | sort -k5 -hr
# Analyze test performance
flutter test --reporter json | jq '.[] | select(.type=="testDone") | {name: .test.name, time: .time}'
Symptoms:
Instant Solutions:
# Check security compliance
flutter analyze | grep -i "security\|encrypt\|audit"
# Validate audit logging
grep -r "audit" lib/core/logging/
# Check encryption implementations
grep -r "encrypt\|crypto" lib/core/security/
Quaex Security Standards:
β Framework Reference: Phase 1.2 - Quaex Impact Analysis Matrix
Symptoms:
Module Validation:
# Test individual modules
flutter test test/modules/finance/
flutter test test/modules/hr/
flutter test test/modules/manufacturing/
flutter test test/modules/supply_chain/
flutter test test/modules/quality/
flutter test test/modules/analytics/
flutter test test/modules/copilot/
# Check module integration points
grep -r "modules/" lib/features/
External System Integration:
β Framework Reference: Phase 2.1 - Quaex Module Dependency Chain Analysis
This help system is continuously updated based on real-world problem resolution in the Quaex Uniform Industrial Platform (UIP) project, maintaining 50-year longevity and industrial compliance standards.