Troubleshooting
Device won't connect via Bluetooth
- Ensure Bluetooth is enabled on your computer:
bluetoothctl power on - Check that your MeshCore device is powered on and in companion mode
- Meshy scans for devices advertising the Nordic UART Service (NUS) UUID
- Try removing the pairing and re-pairing: use your system Bluetooth settings to forget the device, then pair again through Meshy
- Check BlueZ service status:
systemctl status bluetooth - Meshy retries connection 3 times automatically; if all fail, try rebooting the device
Device won't connect via USB
- Check that the USB cable supports data transfer (not charge-only cables)
- Verify the device appears in
/dev/ as ttyUSB0, ttyACM0, or similar - If you see a permission error, click the button to install the udev rule, then unplug and replug the device
- For Flatpak: ensure the device permission is granted in Flatseal or via
flatpak override --user --device=all page.codeberg.sesivany.Meshy - Check dmesg for USB connection errors:
dmesg | grep tty
TCP connection fails
- Verify the companion device is reachable:
ping <IP_ADDRESS> - Check the port is open:
telnet <IP_ADDRESS> 5000 or nc -zv <IP_ADDRESS> 5000 - Ensure firewall isn't blocking the connection
- Verify the companion device is configured for TCP companion mode
- Check companion device logs for connection attempts
QR Scanner doesn't work
- Ensure you have a working webcam:
ls /dev/video* - Grant camera permissions in Flatpak settings (Flatseal or
flatpak override) - Check XDG Camera Portal is running:
systemctl --user status xdg-desktop-portal - Verify PipeWire/GStreamer camera access works in other apps
- For Flatpak, check portal permissions:
flatpak permission-show page.codeberg.sesivany.Meshy
Messages stuck at "Sending" (Pending)
- Check connection status (green indicator in header bar)
- Device battery may be low or turned off
- Radio channel may be congested (high traffic)
- Try enabling Force Flood in contact detail → Routing section
- Check device queue isn't full (Device view → Statistics → Message Queue)
- If disconnected during send, messages are marked failed on reconnect; resend via right-click → Send Again
Messages failing repeatedly
- Verify the contact is reachable (check Last Seen timestamp)
- Try resetting the path: Contact details → Reset Path
- Switch to flood routing temporarily to re-establish path
- Check radio parameters match between all devices
- Verify contact's public key is correct (64 hex characters)
- Check for interference or obstacles blocking signal path
- With 1-byte path hashes, multiple contacts may share the same prefix (hash collision)
- Meshy resolves collisions using geographic proximity, starting from your device's advertised position and chaining through each hop
- If the wrong node is picked, try using 2-byte path hashes in Settings → Routing and Messaging → Default Path Hash Size
- 3-byte hashes provide the most accurate resolution with max 21 hops per path
Channels not working
- Verify all participants use the exact same PSK (32 hex characters for private channels)
- For hashtag channels, ensure the name is identical including the # prefix
- Check channel slots aren't all occupied (the number of available slots depends on the device)
- Verify radio parameters match across all mesh participants
- Try sending a flood-routed advert via Device Actions → Send Advert → Flood Routed
- Contacts need GPS coordinates to appear on map (check Location in contact details)
- Verify contacts have enabled "Include Location in Advert"
- Check map filter toggles in the sidebar aren't hiding contact types
- GPS coordinates of 0.0, 0.0 are filtered out (invalid)
High battery drain on device
- Reduce TX power in Settings → Radio → TX Power
- Increase spreading factor for longer range with less frequent transmissions
- Disable GPS on the device if not needed (Settings → Location → Companion GPS)
- Reduce flood advertisement frequency on repeaters
- Check for routing loops (frequent path resets)