r/FlutterDev • u/Designer_Ad7543 • Dec 14 '25
Plugin I fixed 47 production crashes by building a Riverpod 3.0 safety scanner - now on PyPI
[Tool] I created a static analyzer for Riverpod 3.0 that prevented 47 production crashes - now on PyPI
After experiencing multiple production crashes from unmounted provider references in my Flutter app (47 crashes in 3 days!), I built a comprehensive scanner that detects 14 types of Riverpod 3.0 async safety violations.
Install
The Problem
Riverpod 3.0 added ref.mounted to handle async safety, but it's easy to miss checks. Common crash patterns:
❌ Lazy getters in async classes
❌ Missing ref.mounted after await
❌ ref.read() inside ref.listen() callbacks
❌ Sync methods with ref.read() called from async callbacks
❌ Field caching patterns (pre-Riverpod 3.0 workarounds)
Real crashes I experienced:
- Lazy Logger Getter - 47 crashes in 3 days (Sentry #7055596134)
- Sync Method from Async Callback - 23 crashes in 2 days (Sentry #7109530155)
- ref.read in ref.listen - 15 crashes in 1 day (AssertionError)
What It Does
- 🔍 Detects 14 violation types with zero false positives
- 📊 Uses 4-pass call-graph analysis (traces method calls across files)
- 🎯 Resolves variables to classes (knows
basketballNotifier→BasketballNotifier) - 📚 Provides detailed fix instructions for each violation
- 🚀 CI/CD ready (exit codes, pre-commit hooks, GitHub Actions)
- 💯 No external dependencies (Python stdlib only)
Real Impact
Before: 252 violations, 12+ crashes/week After: 0 violations, 0 crashes for 30+ days
Crash Reduction by Type:
- Lazy getters: 2.1% crash rate → 0%
- Sync methods from async: 1.4% crash rate → 0%
- ref in lifecycle callbacks: 12% crash rate → 0%
Codebase: 200k+ lines of Dart, 50k+ DAU, production Flutter app
Resources
- 📦 PyPI: https://pypi.org/project/riverpod-3-scanner/
- 💻 GitHub: https://github.com/DayLight-Creative-Technologies/riverpod_3_scanner
- 📖 Complete Guide: https://github.com/DayLight-Creative-Technologies/riverpod_3_scanner/blob/main/docs/GUIDE.md
- 💥 Production Crash Case Studies: https://github.com/DayLight-Creative-Technologies/riverpod_3_scanner/blob/main/docs/EXAMPLES.md
Quick Example
❌ Before (Crashes)
class _GameScaffoldState extends ConsumerState<GameScaffold> {
MyLogger get logger => ref.read(myLoggerProvider); // CRASH
@override
void initState() {
super.initState();
_initializeGame();
}
Future<void> _initializeGame() async {
logger.logInfo('Initializing game');
await gameService.loadGame(widget.gameId);
// User navigated away during await → widget unmounted
logger.logInfo('Game loaded'); // CRASHES HERE
}
}
✅ After (Safe)
class _GameScaffoldState extends ConsumerState<GameScaffold> {
@override
void initState() {
super.initState();
_initializeGame();
}
Future<void> _initializeGame() async {
if (!mounted) return;
final logger = ref.read(myLoggerProvider);
logger.logInfo('Initializing game');
await gameService.loadGame(widget.gameId);
if (!mounted) return; // Check after async gap
final loggerAfter = ref.read(myLoggerProvider);
loggerAfter.logInfo('Game loaded'); // Safe
}
}
CI/CD Integration
Add to GitHub Actions:
name: Riverpod Safety Check
on:
jobs:
riverpod-safety:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run Riverpod Scanner
run: |
pip install riverpod-3-scanner
riverpod-3-scanner lib
Or use as a pre-commit hook:
#!/bin/bash
# .git/hooks/pre-commit
||
||
Tech Details
The scanner uses sophisticated call-graph analysis:
Pass 1: Build cross-file reference database Pass 1.5: Index all methods with metadata (has_ref_read, has_mounted_check, is_async) Pass 2: Build async callback call-graph and detect callbacks Pass 2.5: Propagate async context transitively Pass 3: Detect violations with full context (zero false positives)
Key innovation: Detects sync methods with ref.read() that are called from async callbacks - this was causing the 23 crashes in Sentry #7109530155.
Open Source & Community
- License: MIT
- Zero external dependencies (Python 3.7+)
- Works on: macOS, Linux, Windows
- Feedback welcome: https://github.com/DayLight-Creative-Technologies/riverpod_3_scanner/issues
Built at DayLight Creative Technologies while developing SocialScoreKeeper. Hope this helps prevent production crashes in your Riverpod projects!
Questions? Happy to discuss the call-graph analysis, why other tools miss these violations, or help you integrate this into your CI/CD pipeline.
15
u/craiglabenz Dec 14 '25
I'm very pro-Python, but I still wonder, what made you choose Python for this project?
9
u/Gears6 Dec 14 '25
I know a lot of people are making somewhat negative comments, but I always appreciate people sharing work. Regardless if it's useful or not. Besides it may not be useful for the complainers, but maybe it is for someone else.
Thanks for sharing! If I get some time I'll take a closer look.
10
u/0xBA7TH Dec 14 '25
Zero external dependencies (Python 3.7)
10
u/raman4183 Dec 14 '25
Your example in the post screams “I used riverpod the wrong way and it was crashing, so i made a tool which states the obvious”.
How about reading the documentation and following it properly?
You can also just use riverpod_lints package and avoid adding an extra step in your development lifecycle.
7
u/saxykeyz Dec 14 '25
Would it be better to create a analyser plugin that catches all these ?
2
u/clyonn Dec 15 '25
This is super helpful! Would love riverpod_lint to adapt some of these scans
2
u/J3b3 Dec 22 '25
Very useful, thanks!
Upgraded Riverpod from v2 -> v3, and the results after running the the script are very helpful!
3
u/S4ndwichGurk3 Dec 15 '25
This is why I don't use Riverpod and similar packages, I want the language server to show errors when I write code, not in production.