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.