taler-android

Android apps for GNU Taler (wallet, PoS, cashier)
Log | Files | Refs | README | LICENSE

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.