taler-android

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

fresh-instance-cannot-be-used.md (3884B)


      1 # A freshly provisioned merchant instance cannot be used at all
      2 
      3 > **Fixed on master** (checked 2026-11-08, commit `24f7b249`). See [STATUS.md](STATUS.md) for the fix and the test that pins it.
      4 
      5 **Severity:** high for a new user -- it is the first thing a merchant who has
      6 just created an instance will see, and what they see is "Error: No valid
      7 product category found" and a return to the login screen. There is nothing in
      8 the message that tells them to go and add a product, and nothing they can do
      9 in the terminal to get past it.
     10 
     11 **Where:**
     12 `merchant-terminal/src/main/java/net/taler/merchantpos/order/OrderManager.kt`
     13 (the category check) and
     14 `merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigManager.kt`
     15 (`onMerchantConfigReceived`, which treats any receiver's complaint as a
     16 configuration failure).
     17 
     18 **Found by:** `pos-simulator`, scenario `fresh_instance_no_inventory`, against
     19 `backend/mockd.py --profile fresh`.
     20 
     21 ## What happens
     22 
     23 Point the terminal at an instance whose `/private/pos` answers
     24 
     25 ```json
     26 {"categories": [], "products": []}
     27 ```
     28 
     29 which is what a self-provisioned instance answers until somebody adds a
     30 product. The terminal fetches it, refuses it, and goes back to the login
     31 screen:
     32 
     33 ```
     34 dialog: 'Taler POS': 'Error: No valid product category found' ['OK']
     35 ```
     36 
     37 The terminal has two order screens, and only one of them needs an inventory.
     38 "Order by amount" is a keypad: a cashier types a price and bills it, and no
     39 product is involved at any point. It is also the default -- `InitialOrderScreen`
     40 starts as `AmountEntry`. But the configuration never finishes, so neither
     41 screen is reached.
     42 
     43 ## Why
     44 
     45 `ConfigManager.onMerchantConfigReceived` hands the fetched configuration to
     46 every registered `ConfigurationReceiver` and aborts on the first one that
     47 objects:
     48 
     49 ```kotlin
     50 for (receiver in configurationReceivers) {
     51     val result = try { receiver.onConfigurationReceived(...) } catch (e: Exception) { ... }
     52     if (result != null) { // error
     53         if (!silent) mConfigUpdateResult.postValue(ConfigUpdateResult.Error(result))
     54         return
     55     }
     56 }
     57 ```
     58 
     59 The only receiver is `OrderManager`, which objects when there are no usable
     60 categories -- reasonably, from its own point of view: it is the inventory
     61 screen's model and it has no inventory to show. But its objection becomes the
     62 whole app's configuration failure, including for the screens that do not depend
     63 on it.
     64 
     65 Note that `merchantConfig`, `currency` and `currencySpec` are assigned *after*
     66 that loop, so a refusal also leaves the terminal with no currency -- which is
     67 why there is no way to carry on in a degraded mode from where it stops.
     68 
     69 ## Reproducing it
     70 
     71 ```bash
     72 cd /tmp/taler-pos-sim/driver && . ../env.sh
     73 python3 ../findings/repro_fresh_instance_unusable.py
     74 ```
     75 
     76 Against a real backend: self-provision an instance, add no products, and log
     77 the terminal in to it.
     78 
     79 ## What a fix has to decide
     80 
     81 This one needs a product decision, so no patch is included.
     82 
     83 The narrow reading is that an instance with no products should still configure,
     84 with the inventory screen showing an empty state and "Order by amount"
     85 working -- which means `OrderManager` returning `null` for an empty inventory
     86 rather than an error, and the inventory screen gaining an empty state. That
     87 also makes the error message honest again: `config_error_category` would then
     88 mean what it says, "a product references a category that does not exist",
     89 rather than doubling as "this instance is new".
     90 
     91 The wider reading is that a receiver's objection should not be the app's
     92 objection: `ConfigManager` could record it, finish the configuration, and let
     93 each screen decide whether it can work. That is the better shape but a larger
     94 change.
     95 
     96 Either way the message wants rewording: "No valid product category found" is
     97 about the terminal's data model, and the person reading it is a merchant who
     98 has not added a product yet.