taler-android

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

release-error-screen-explains-nothing.md (8074B)


      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 # In a release build, an error screen can explain nothing at all
     18 
     19 Found by the `error_screen_without_dev_mode` scenario, written because
     20 everything else in this campaign runs with developer mode on — where the error
     21 screen prints the whole error as JSON and the defect is invisible.
     22 
     23 **Severity: moderate, release builds only.** It applies to every error whose
     24 explanation wallet-core puts somewhere other than `hint` or `message`, which
     25 includes `WALLET_CORE_API_BAD_REQUEST` (7048) — one of the codes this campaign
     26 hit in ordinary runs.
     27 
     28 ## What happens
     29 
     30 With developer mode **on**, an error with no hint and no message shows the raw
     31 object, which at least names the code:
     32 
     33 ```
     34 Error
     35 {
     36   "code": 7001,
     37   "hint": null,
     38   "message": null
     39 }
     40 Export error diagnostics   [Copy] [Share]
     41 ```
     42 
     43 With developer mode **off** — which is what a release build is — the same error
     44 shows:
     45 
     46 ```
     47 Error
     48 Export error diagnostics   [Copy] [Share]
     49 ```
     50 
     51 An icon, the word "Error", and an invitation to export diagnostics. Nothing
     52 about what failed, what to do, or which operation it was.
     53 
     54 ## Why
     55 
     56 `ErrorComposable` has two branches, and the release one prints a single string:
     57 
     58 ```kotlin
     59 // wallet/src/main/java/net/taler/wallet/compose/ErrorComposable.kt:105
     60 if (devMode) {
     61     … Text(text = jsonError, fontFamily = FontFamily.Monospace) …
     62 } else {
     63     Text(text = error.userFacingMsg, …)
     64 }
     65 ```
     66 
     67 and that string is the hint and the message concatenated, with no fallback:
     68 
     69 ```kotlin
     70 // wallet/src/main/java/net/taler/wallet/backend/WalletResponse.kt:81
     71 val userFacingMsg: String
     72     get() = StringBuilder().apply {
     73         if (extra.containsKey("errorResponse")) { … }
     74         else {
     75             hint?.let { append(it) }
     76             message?.let { append(" ").append(it) }
     77         }
     78     }.toString()
     79 ```
     80 
     81 Both null gives the empty string, and `Text("")` is nothing.
     82 
     83 This is not hypothetical. wallet-core puts the explanation of a bad request in
     84 `detail`, which this very campaign has logged:
     85 
     86 ```
     87 {"type":"error","operation":"addExchange","id":100,
     88  "error":{"code":7048,"detail":"URL cannot be parsed"}}
     89 ```
     90 
     91 `detail` is not lost — the custom `TalerErrorInfoSerializer` keeps every
     92 unknown key in `extra`, and the "Copy"/"Share" buttons export the complete
     93 object including it. It is simply never *shown*: `userFacingMsg` looks at
     94 `hint`, at `message`, and at one special case (`extra["errorResponse"].hint`),
     95 and at nothing else.
     96 
     97 The other end of the same problem: whatever *is* in `message` goes to the user
     98 verbatim, exception class names included. Feeding the balance screen a reply
     99 with an out-of-spec currency (`api_response_hostile`) produced
    100 
    101 ```
    102 {"code": 0, "hint": "",
    103  "message": "net.taler.common.AmountParserException: Invalid currency: VERYLONGCURRENCY"}
    104 ```
    105 
    106 so a release build would show the user a Java class name — and the whole
    107 balance screen becomes an error page, which for a *rejected* value is the right
    108 severity but the wrong words.
    109 
    110 The mailbox screen does not even go through `ErrorComposable`; it interpolates
    111 the error object into a string:
    112 
    113 ```kotlin
    114 // wallet/src/main/java/net/taler/wallet/mailbox/MailboxScreen.kt:150
    115 is MailboxResult.Error -> Text("Error: ${res.error}", modifier = Modifier.padding(16.dp))
    116 ```
    117 
    118 which is a Kotlin data-class dump. Typing a malformed mailbox URL puts this on
    119 the screen, in any build:
    120 
    121 ```
    122 Error: TalerErrorInfo(code=WALLET_UNEXPECTED_EXCEPTION, hint=unexpected
    123 exception (message: Invalid base URL: http://localhost:11000unet.org),
    124 message=null, extra={when={"t_ms":…}, stack="    at URLImpl (<compiled_js>:4523:28)
    125     at registerMailbox (<compiled_js>:…
    126 ```
    127 
    128 — a QuickJS stack trace, shown to the user, on a screen that is not
    129 developer-mode gated.
    130 
    131 ## Reproduce by hand
    132 
    133 Needs a debug build (to deliver the URI) and one trip through the developer
    134 mode switch:
    135 
    136 1. Enable **Developer mode** in Settings.
    137 2. Queue an error with neither hint nor message — `{"code": 7001}`, base64url
    138    encoded:
    139 
    140    ```bash
    141    adb shell am start -a android.intent.action.VIEW -d \
    142      'taler+http://dev-experiment/api-error?operation=getBalances&detail=eyJjb2RlIjogNzAwMX0&count=20'
    143    ```
    144 
    145 3. Go to the main screen: the error screen appears with the JSON.
    146 4. Turn **Developer mode** off and go back to the main screen.
    147 5. The error screen now shows only "Error" and the export buttons.
    148 
    149 A release build reaches the same state without step 1 or 4, with any error of
    150 that shape — for example by adding `file:///etc/passwd` as a payment service,
    151 whose refusal is a 7048 with only a `detail` (that one is also never shown at
    152 all; see
    153 [`add-payment-service-fails-silently.md`](add-payment-service-fails-silently.md)).
    154 
    155 ## Reproduce with the simulator
    156 
    157 ```bash
    158 ssh root@tripwire.taler.net
    159 cd /opt/taler-sim/driver
    160 python3 ../findings/repro_release_error_screen.py
    161 SIM_WORKER=4 python3 suite.py error_screen_without_dev_mode
    162 ```
    163 
    164 The notes record the screen with developer mode on, then off, and list
    165 everything on the second one that could explain the error — which is nothing.
    166 
    167 ## Fix
    168 
    169 `release-error-screen-explains-nothing.diff` makes the error sheet fall back to
    170 the code when there is no text to show:
    171 
    172 ```kotlin
    173 // wallet/src/main/java/net/taler/wallet/compose/ErrorComposable.kt
    174 text = error.userFacingMsg.ifEmpty {
    175     stringResource(R.string.error_code_only, error.rawCode)
    176 },
    177 ```
    178 
    179 with `<string name="error_code_only">Error code %1$d</string>` beside it, and
    180 `userFacingMsg` left honest — trimmed, and empty when the error carries nothing
    181 — with a doc comment saying where the fallback belongs. `rawCode` rather than
    182 `code.code`, because a code newer than this app's registry is preserved there
    183 while `code` has become `-1`.
    184 
    185 The screen then reads:
    186 
    187 ```
    188 Error
    189 Error code 7001
    190 Export error diagnostics   [Copy] [Share]
    191 ```
    192 
    193 ### What running it changed
    194 
    195 The first version of this patch put the fallback inside `userFacingMsg` itself
    196 and rendered `"Error code ${code.code} (${code.name})"`. It compiled, it
    197 lint-passed, and on a device it produced:
    198 
    199 ```
    200 Error code 7001 (WALLET_UNEXPECTED_EXCEPTION)
    201 ```
    202 
    203 which the simulator immediately flagged as an `internal-error-screen` — its
    204 oracle looks for words like "unexpected" and "exception" on screen, on the
    205 grounds that they should not reach a user, and it was right. The enum name is
    206 an identifier for developers; it is also untranslatable English in a UI that is
    207 otherwise localised, and `TalerErrorInfo` has no `Context` to localise with.
    208 Moving the fallback to the sheet, where there *is* a `Context`, fixes both: the
    209 string is in `strings.xml` like every other, and the user sees a number they can
    210 report rather than a phrase that reads like a crash.
    211 
    212 The second version was re-run on the same scenario, on a device, and the sheet
    213 is now recorded as an ordinary error screen rather than an internal one:
    214 
    215 ```
    216   error_screen_without_dev_mode ok            0 serious, 2 total, 128.7s
    217       [error-screen] { "code": 7001, "hint": null, "message": null }
    218       [error-screen] Error code 7001
    219 ```
    220 
    221 Worth noting for whoever takes this further: the other six places that render
    222 `userFacingMsg` — the transactions list, the peer screens, the contact and
    223 alias screens, and `TestWithdrawStatus` — still show nothing for an error that
    224 carries neither hint nor message. The sheet is the one a release user meets
    225 first, which is why the patch stops there.