config-change-locks-the-wallet-out-of-its-database.md (9065B)
1 <!-- 2 This file is part of GNU Taler 3 (C) 2026 Taler Systems S.A. 4 5 GNU Taler is free software; you can redistribute it and/or modify it under the 6 terms of the GNU General Public License as published by the Free Software 7 Foundation; either version 3, or (at your option) any later version. 8 9 GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU General Public License for more details. 12 13 You should have received a copy of the GNU General Public License along with 14 GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 --> 16 17 # A configuration change locks the wallet out of its own database 18 19 Found while setting up a different test — switching the app's language to 20 German to read the contacts screen — which is as ordinary a thing as a user 21 does. Enlarging the system font or the display size does it too. 22 23 **Severity: high.** The wallet lands on its "Initialization error" screen, 24 which replaces the entire app, and the screen tells the user to retry while 25 offering no way to do so; the only way out is to swipe the app away and reopen 26 it. The error underneath is `WALLET_UNEXPECTED_EXCEPTION` (7001), not a handled 27 condition. Two of the three triggers are **accessibility** settings, so the 28 users most likely to meet it are the ones who changed their font size to be 29 able to read the screen at all. 30 31 ## What happens 32 33 With the wallet open, set its language: 34 35 ```bash 36 adb shell cmd locale set-app-locales net.taler.wallet.fdroid.debug --locales de-DE 37 ``` 38 39 The app comes back in German — on this screen: 40 41 ``` 42 Fehler 43 Beim Starten der Wallet ist ein Fehler aufgetreten. Dies kann nach einem 44 App-Update oder bei inkompatiblen Wallet-Daten passieren. Bitte versuche es 45 erneut, … 46 { 47 "code": 7001, 48 "hint": "unexpected exception (message: could not acquire exclusive ownership 49 of the wallet database; another wallet process may still be using it)", 50 "message": null, 51 "stack": " at acquireSqliteWalletDbOwnership (<compiled_js>:34739:20)" 52 } 53 [Fehlerdiagnose exportieren] [Kopieren] [Teilen] 54 ``` 55 56 The configuration change restarts the app, the new instance asks wallet-core to 57 `init`, and wallet-core cannot take the SQLite database because the instance it 58 replaced has not let go of it yet. 59 60 ## Which changes do it 61 62 Four everyday configuration changes, each applied while the wallet was open on 63 a settings sub-screen, then undone and the app relaunched: 64 65 | Change | Init error | Still broken after relaunching | 66 | --- | --- | --- | 67 | app language (`cmd locale set-app-locales … de-DE`) | **yes** | no | 68 | system font size (`settings put system font_scale 1.30`) | **yes** | no | 69 | display size (`wm density 480`) | **yes** | no | 70 | dark mode (`cmd uimode night yes`) | no | — | 71 72 Nothing is lost: killing the app and reopening it recovers, and undoing the 73 change is not necessary. But nothing *in* the app recovers. 74 75 Dark mode is the exception for a reason — the manifest already handles it: 76 77 ```xml 78 <!-- wallet/src/main/AndroidManifest.xml:65 --> 79 android:configChanges="keyboardHidden|orientation|screenSize|uiMode" 80 ``` 81 82 `uiMode` and `orientation` are in that list, so dark mode and rotation never 83 recreate the activity. Locale, `fontScale` and `density` are not, so they do — 84 and that is the whole trigger. 85 86 ## Why it happens 87 88 It is the same process throughout — measured, not assumed: 89 90 ``` 91 pid before: 13611 92 pid after: 13611 93 same process: True 94 init error: True 95 ``` 96 97 so the message's "another wallet process" is itself misleading: the lock is 98 held by the previous wallet instance *inside this process*, which was never 99 shut down. The activity's two lifecycle halves do not agree about that: 100 101 ```kotlin 102 // wallet/src/main/java/net/taler/wallet/main/MainActivity.kt:241 103 model.startWallet() // in onCreate, unconditionally 104 105 // wallet/src/main/java/net/taler/wallet/main/MainActivity.kt:414 106 // wallet-core belongs to the retained MainViewModel, not to this activity 107 if (!isChangingConfigurations) model.stopWallet() 108 ``` 109 110 The `onDestroy` side is right, and its comment says why: wallet-core belongs to 111 the retained `MainViewModel`, so a configuration change must not shut it down. 112 The `onCreate` side then starts it again anyway. `startWallet()` is not 113 idempotent in the way that needs: 114 115 ```kotlin 116 // wallet/src/main/java/net/taler/wallet/backend/WalletBackendApi.kt:44 117 fun startWallet() { 118 backendManager.run() // a no-op, it is already running 119 GlobalScope.launch(Dispatchers.IO) { sendInitMessage() } // a *second* init 120 } 121 ``` 122 123 `backendManager.run()` does nothing the second time — its `running` flag and 124 the static `coreRunning` guard both hold, and indeed "refusing to run a second 125 wallet-core in this process" never appears in the log. The second `init` 126 message is the problem: wallet-core logs it as a "repeat initialization" and 127 builds a fresh wallet on the same core, which then cannot take the SQLite 128 database from the instance still holding it. 129 130 Whether it fails at all is a race with the old instance letting go — the same 131 change applied while the wallet sits on its home screen sometimes survives, and 132 wallet-core logs `request-finish-success` for the repeat init. That is why this 133 reproduces reliably from a settings sub-screen and only sometimes from the 134 balance screen. 135 136 ## Why the screen is a dead end 137 138 `MainActivity` swaps the whole navigation graph for the error screen: 139 140 ```kotlin 141 // wallet/src/main/java/net/taler/wallet/main/MainActivity.kt:155 142 initError?.let { error -> 143 WalletInitErrorScreen(model = model, error = error, …) 144 } ?: run { 145 WalletNavHost(…) 146 } 147 ``` 148 149 and `WalletInitErrorScreen` offers exactly two buttons — **Export logs** and 150 **Export database**. Meanwhile the message it shows says: 151 152 ```xml 153 <!-- res/values/strings.xml:70 --> 154 <string name="wallet_init_error_message">An error occurred while starting the 155 wallet. … Please retry, and if the problem persists, export the logs and report 156 this issue to the developers.</string> 157 ``` 158 159 There is nothing to retry *with*. `initError` is a `StateFlow` that is only 160 cleared by a later successful init: 161 162 ```kotlin 163 // wallet/src/main/java/net/taler/wallet/main/MainViewModel.kt:177,192 164 override fun onInitErrorReceived(error: TalerErrorInfo) { mInitError.value = error } 165 override fun onInitReceived(init: InitResponse) { … mInitError.value = null … } 166 ``` 167 168 and nothing asks for another init. So for the life of that process the wallet is 169 a single screen with two export buttons. 170 171 ## Reproduce by hand 172 173 1. Open the wallet and leave it on a settings sub-screen (Settings → Contacts 174 is where this was first seen). 175 2. Make one of the three changes: 176 * *App info → Language* for this app, or 177 `adb shell cmd locale set-app-locales <pkg> --locales de-DE`; 178 * *Settings → Display → Font size*, or 179 `adb shell settings put system font_scale 1.30`; 180 * *Settings → Display → Display size*, or `adb shell wm density 480`. 181 3. The wallet comes back on the Initialization error screen. With developer 182 mode on, the `7001` object quoted above is on screen; without it, the hint 183 alone. 184 4. Nothing on the screen gets the wallet back. Swiping the app away from the 185 task switcher and reopening it does. 186 187 Undo with `--locales` (no value), `font_scale 1.0`, `wm density reset`. 188 189 ## Reproduce with the simulator 190 191 ```bash 192 ssh root@tripwire.taler.net 193 cd /opt/taler-sim/driver 194 python3 ../findings/repro_config_change_db_ownership.py emulator-5554 195 ``` 196 197 It is also measured every round now, over all four changes at once: 198 199 ```bash 200 cd /opt/taler-sim/driver && SIM_WORKER=0 python3 -u suite.py config_changes 201 ``` 202 203 ## Suggested fix 204 205 The one-line version: **do not start the wallet again when it is already 206 running.** `MainActivity.onCreate` calls `startWallet()` on every activity 207 creation, while `onDestroy` deliberately does not stop it across a 208 configuration change; making the start side agree with the stop side — 209 `if (!model.walletRunning) model.startWallet()`, or moving the call into 210 `MainViewModel`'s initialiser, where the retained lifetime already lives — ends 211 it. 212 213 Three smaller things are worth doing anyway, because each one would have turned 214 this into a non-event: 215 216 1. **Make `init` idempotent, or wait briefly for the lock.** A repeat `init` 217 whose predecessor is still letting go of the database could reuse it or 218 retry for a few hundred milliseconds instead of failing. 219 2. **Retry init from the error screen.** The message already promises it: 220 "Please retry". A button calling `model.startWallet()` would honour the 221 promise, and would cover every other transient init failure as well. 222 3. **Say "the database is busy", not "unexpected exception".** 7001 with a 223 compiled-JavaScript stack trace is what the user is shown for a condition 224 the wallet understands perfectly well — and the text blames "another wallet 225 process", which measurement shows is this very process.