+++
title = "Troubleshooting"
weight = 13
+++

## 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

## Contact path shows wrong hops

- 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

## Map not showing contacts

- 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)
