Troubleshooting¶
Last updated
The things that most often surprise people running Stolo on iPhone, especially with a long-range radio connected over Bluetooth.
Nearly everything on this page is normal behaviour with a short wait or a single step attached to it. Work down the entry that matches what you are seeing before changing anything else. For what every control in the app does, see Settings.
Starting up¶
The app says it is not connected when you first open it¶
| What you see | For the first few seconds after launch, Stolo reports that it cannot reach its backend, and nothing loads. |
| Why it happens | Stolo brings its networking up as it launches, and the rest of the app waits for that to finish. That normally takes up to about ten seconds. It takes longer if you have a radio configured but switched off, because Stolo spends time looking for that radio before giving up on it for this session. |
| What to do | Wait — it clears on its own. If it still says no connection after roughly half a minute, close the app fully and reopen it, as described next. |
You need to restart Stolo¶
| What you see | Something has gone sideways — a setting is not taking effect, or the app has asked you to restart — and you are looking for a restart button. |
| Why it happens | On iPhone there is no separate restart: the in-app option will simply tell you to do it by hand. |
| What to do | Close Stolo completely, then open it again. That is the restart. |
To close it completely: swipe up from the bottom of the screen to open the app switcher, then swipe the Stolo card away.
Backgrounding the app or locking the phone is not the same thing. Only swiping the app away in the app switcher counts.
Pairing a radio over Bluetooth¶
Pair from inside Stolo, not from iPhone Settings¶
| What you see | The radio does not appear under iPhone Settings → Bluetooth, or it appears there and pairing fails. |
| Why it happens | iOS cannot pair this class of device from its own Settings screen. Pairing has to be started by the app that will use the radio. |
| What to do | Put the radio in pairing mode, then in Stolo go to Add a connection → Bluetooth → Scan and pick your radio from the list. |
This is the only supported way to pair a radio. If you have already paired it in iPhone Settings, forget it there first.
The six-digit code flashed past, or never appeared¶
| What you see | You tap the radio in Stolo and the code on the radio’s screen disappears before you can read it — or no code ever shows. |
| Why it happens | The radio’s pairing window is short: about 35 seconds from the moment you put it into pairing mode. Once that window closes, the attempt goes nowhere. |
| What to do | Work quickly, and in the right order — see the steps below. |
- Put the radio in pairing mode.
- Tap it in Stolo straight away.
- Type the six-digit code from the radio’s screen as soon as it appears.
If the window has already expired, put the radio back into pairing mode and start again from step 1. Retrying against a radio that has dropped out of pairing mode will not work.
Paired, but the radio is not carrying any traffic yet¶
| What you see | The radio shows as paired and connected, but messages do not move over it. Stolo may be showing a notice asking you to restart. |
| Why it happens | A freshly paired radio sometimes needs the app to start up with it already in place before it is brought into the mesh. |
| What to do | Close Stolo fully and reopen it once. |
You only need this after the initial pairing — not every time you use the radio.
A radio that keeps dropping¶
A radio that used to work keeps dropping the connection¶
| What you see | The radio connects and then disconnects again within about a second, over and over. Stolo reports that the radio keeps dropping the connection. |
| Why it happens | The phone and the radio each store a record of their pairing, and the two no longer agree — one side thinks they are paired and the other does not. The usual cause is re-flashing the radio’s firmware, which wipes the pairings stored on the radio while your iPhone still holds its side. |
| What to do | Clear the stale pairing on both sides, then pair again from inside Stolo. |
- On the iPhone, open Settings → Bluetooth. If the radio is listed, tap the info button next to it and choose Forget This Device.
- Power the radio off and on again.
- If it still refuses to stay connected, the pairings stored on the radio itself need clearing. Put it back into pairing mode and consult your radio’s documentation for how to erase its saved pairings.
- Pair again from inside Stolo (Add a connection → Bluetooth → Scan).
A plain power-cycle does not erase the pairings stored on the radio. If step 2 did not help, you need step 3.
How long a radio takes to come back after being switched off¶
| What you see | You power the radio back on and it is not connected yet. |
| Why it happens | Nothing is wrong. The radio has to finish booting before the phone can reach it, and that boot time is most of the wait. |
| What to do | Give it roughly 5 to 30 seconds. A paired radio reconnects by itself, with nothing needed from you. |
The first time you try this, keep Stolo open on screen so you can watch the connection come back.
Range and interference¶
The link is weak even though the radios are close together¶
| What you see | Two radios are a short distance apart, but the link is poor or messages do not get through — while transmitting appears to work fine. |
| Why it happens | Phones, laptops and USB-3 hubs throw off a surprising amount of electrical noise in the same band the radio listens on. It deafens the radio’s receiver without affecting what it transmits, which is why one direction can look healthy while nothing arrives. |
| What to do | Give the radio room — see below. |
- Keep it a metre or more away from phones, laptops and USB hubs.
- Run it on battery rather than powered from a computer where you can.
- If range is still poor, move the radio away from the noisy equipment before assuming the radio or the antenna is at fault.
Messages¶
Messages do not get through right after both phones come online¶
| What you see | Two people are both online, but early messages sit unsent or take a while to land. |
| Why it happens | The mesh has to work out a path between the two devices, and that settles shortly after everyone is up rather than instantly. |
| What to do | Give it a few minutes before troubleshooting anything else. Routes generally sort themselves out, and messages sent in the meantime deliver once a path exists. |
Sending a diagnostics report¶
Some failures cannot be fixed on your phone. If your network’s contact service says it has no allocation, or that it is full, the fix is on the side of whoever runs it — and they need to know what your device is actually seeing before they can do anything.
Stolo builds that for you. Open Settings › Help & support › Diagnostics, or tap the ⋮ on the network card at the top of People and choose Diagnostics. You will see the whole report before you send it, and a button to copy it.
What the report contains¶
| Versions | Your Stolo version and build, and the versions of the networking components it is running — Reticulum, LXMF, Python — plus your device’s operating system. Most “works on mine” questions end here. |
| Your Stolo ID | The same identity hash you share when someone adds you as a contact. It is how an operator finds your device in their records. |
| Connections | Every connection you have, its type, whether it is switched on, whether it is actually up, and how many peers it can see. This is what shows whether the gateway link is alive at all. |
| Networks | Each network you belong to, whether you trust it, and whether you hold its keyset. |
| Contact service | Whether it is configured, its current state, when it last synced, how many members it listed, and every error it is reporting — not just the one on screen. |
The report carries no message text, no contact names, no keys and no location. It describes your setup, not what you have said or where you are.
Who to send it to¶
Send it to whoever runs the contact service your network points at.
- If your network runs on the contact service Stolo hosts, that is us — paste the report into the contact form on our website.
- If someone in your organisation stood up their own contact service, send it to them. They can act on it without involving us at all.
What an operator does with it¶
| “This network has no contact-service allocation” | The network exists, but nothing has been provisioned for it on the service. The operator matches the network id in the report against their records and connects it. |
| “This network or gateway is at capacity” | The member list is full. The operator uses the member count and the network id to decide whether to raise the allocation or clear out devices that are gone. |
| Nothing syncs, but no error is shown | The connections list usually settles this in a second: if no connection is up, the problem is between your phone and the network, not on the service at all. |
If you are not sure which applies, send the report anyway. It is short, and it is the same set of facts either way.
Still stuck?¶
If nothing above matches what you are seeing, reach us through the contact form on our website. Include:
- your device model,
- your radio model,
- and what you saw on screen.
That is usually enough for us to spot it.