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