MeshCore Network Troubleshooting Reference

A systematic approach to troubleshooting MeshCore network issues saves time and frustration. This reference covers the most common problems and their diagnostic approaches.

Diagnostic Framework

When a problem is reported, ask these questions in order:

1. Is the problem isolated to one node pair, or affecting all nodes?
2. Is the problem one-directional or bidirectional?
3. Did it work before? What changed?
4. Is the issue at the RF layer (no signal) or the protocol layer (signal present, no delivery)?

Problem: Node Not Seen by Others

Symptoms: A node is powered on but doesn't appear in other nodes' neighbor lists or can't communicate with anyone.

Diagnostics:

• Check: Is the node's LoRa radio initialized? (Serial CLI: status)
• Check: Is the frequency/preset matching other nodes? (Verify with get lora)
• Check: Is the antenna connected? (Transmit without antenna = immediate hardware risk on some boards)
• Check: Is the channel key matching? (Different key = nodes don't recognize each other's packets)
• Check: Is there a hardware failure? (Try a different known-good node at the same location)

Problem: Messages Not Delivered

Symptoms: Nodes can see each other but messages don't arrive, or arrive with high latency.

• SNR below -15 dB: Signal is present but too weak. Add a repeater or improve antennas.
• High channel utilization: Too many nodes flooding the network. Check for misconfigured flooding, reduce hop limit.
• Path discovery failure: path discovery flood is flooding but path response is not returning. One-way link - the return path may be blocked by terrain or a directional antenna pointing wrong way.
• Room server not receiving messages: Check that room server's attached LoRa node is on the correct channel and hearing the network.

Problem: Room Server Clients Not Syncing

Symptoms: App connects to room server but doesn't show recent messages or shows empty history.

• Check room server connectivity: ssh pi@room-server journalctl -u meshcore-roomserver -n 50
• Check message count: messages count from room server CLI
• Check port: Default port 5005 - is the firewall allowing connections?
• Check key: Room key must match between app configuration and server configuration

Problem: Repeater Goes Offline Periodically

Symptoms: A backbone repeater disappears from the network at irregular intervals, then reappears.

• Power issue: Insufficient solar charging, battery capacity degradation. Check voltage logs.
• Firmware watchdog: nRF52840 watchdog timer should prevent lockups but may be triggering reboots on firmware bugs. Check for panic/reset logs in serial output.
• Thermal issue: Summer heat causing processor throttling or thermal shutdown. Check enclosure temperature.
• Memory leak: Known issue in some firmware versions with long uptime. If reboot schedule resolves it, update firmware or add a periodic reboot cron job.

Useful CLI Diagnostic Sequence

# Connect to node serial console
screen /dev/ttyUSB0 115200

# Full status check:
status # Overall health
repeaters # List heard repeaters and their signal
stats # Packet counts (received/forwarded/dropped)

# Check a specific path:
# (Send a traceroute to see path to another node)
traceroute !targetNodeId

# Check room server connectivity:
federation list # Shows federation peers and last sync time
clients # Shows connected clients