Common Failures

Build And Gradle

Symptom	Likely Cause	Fix
Compose compiler or Kotlin mismatch	Stale dependency versions	Verify AGP, Kotlin, Compose BOM, and compiler setup from official docs
KSP task fails after adding Room	KSP plugin missing or version mismatch	Add KSP intentionally and use `ksp`, not both `ksp` and `annotationProcessor`
Release task missing	Module or variant name differs	Run `./gradlew tasks` and use project-specific names
Debug works but release fails	R8, signing, or manifest difference	Build release early, not at the end

Compose UI Bugs

Symptom	Likely Cause	Fix
Infinite recomposition	State write during composition	Move writes to event handlers or side effects
List loses row state	Missing stable keys	Use `items(items, key = { it.id })`
Preview crashes	Preview constructs real dependencies	Preview stateless composables with fake state
Slow scroll	Heavy row composition or unstable models	Keep rows small, use stable models, profile on device
Text unreadable in dark mode	Hard-coded colors	Use Material 3 color roles

Room Data Loss

Symptom	Likely Cause	Fix
Data disappears after update	Destructive migration	Write real migrations and migration tests
Query fails at runtime	Schema mismatch or untested query path	Use Room compile-time checks and tests
UI freezes during import	Main-thread parsing or huge transaction	Move work off main thread and chunk large imports
Export misses user edits	Export reads raw import data only	Export from normalized source-of-truth tables

WorkManager Not Running

Symptom	Likely Cause	Fix
Job never starts	Constraints not met	Inspect constraints and test with relaxed constraints
Job runs repeatedly	Unique work policy wrong	Use explicit unique work name and policy
Job fails forever	Retry without fatal/error split	Return `failure` for bad input and `retry` only for retryable failures
Works on emulator, not device	OEM battery behavior	Test on physical target device and avoid exact timing promises

Play Console Rejections

Symptom	Likely Cause	Fix
SMS permission rejected	Core functionality or declaration unclear	Rework feature, fallback, privacy policy, and demo evidence
Target API warning	Requirements drifted	Update target API after checking current Play requirement
Data safety rejected	Answers do not match behavior	Audit actual collection, storage, sharing, and deletion
Artifact rejected	Debug, unsigned, or wrong format	Upload signed AAB for Play release
Signing issue	Upload key mismatch	Check Play App Signing page and signing report

Triage Order

Reproduce on command line.
Capture exact command and error.
Check whether the issue appears in debug and release.
Check whether it reproduces on physical device.
Verify dependency and policy freshness from official sources.
Fix the smallest owning layer.