# 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 reporting healthy state? (Serial CLI: `stats-core` for battery/uptime/queue length and `stats-radio` for noise floor, last RSSI/SNR, airtime and receive errors)
- Check: Is the frequency/preset matching other nodes? (Verify with `get radio`, which shows freq/bw/sf/cr, or `get freq`)
- Check: Is the antenna connected? (Operate with an antenna or dummy load attached; transmitting into an open or badly mismatched port can stress the power amplifier 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.

- **Low SNR (link near the demodulation floor):** LoRa's minimum decodable SNR depends on the configured spreading factor — roughly -7.5 dB at SF7 down to about -20 dB at SF12 (per Semtech SX126x datasheets). If the measured SNR is near or below the floor for your SF, the link is marginal: raise the spreading factor, improve antennas, or add a repeater. A single flat threshold (such as "-15 dB") is misleading because it is undecodable at low SF yet still usable at SF12.
- **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 that the room server is actually hearing the mesh: connect to its serial console and run `stats-radio` (noise floor, last RSSI/SNR, receive errors) and `stats-packets` (received/sent packet counters).
- Check the access control list with `get acl` to confirm the connecting client is permitted.
- Check key: Room key (and admin password) must match between app configuration and server configuration. The default admin password is `password` and should be changed.
- Note: a MeshCore room server is LoRa firmware running on an embedded radio device — it is not a Linux daemon listening on a TCP port. There is no firewall/IP port to open for the room server itself. (For reference, the `meshcore-cli` host tool's TCP companion connection defaults to port 5000, not a room-server port.)

## 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.
- **Stability over long uptime:** If a periodic reboot reliably resolves the symptom, update to the latest firmware first. A scheduled reboot can serve as a generic mitigation while you isolate the cause; if you can reproduce a specific fault, file it against the firmware repo with the version and serial logs.

## Useful CLI Diagnostic Sequence

```
# Connect to node serial console (device path varies:
# /dev/ttyUSB0 or /dev/ttyACM0 on Linux, COMx on Windows; 115200 baud is correct)
screen /dev/ttyUSB0 115200

# Health and radio state:
stats-core      # Battery, uptime, queue length, debug flags
stats-radio     # Noise floor, last RSSI/SNR, airtime, receive errors
get radio       # Current freq/bw/sf/cr

# Heard nodes and packet counters:
neighbors       # List recently-heard neighbors (encoded as pubkey-prefix:timestamp:snr*4)
stats-packets   # Packet counters (Received, Sent)

# Firmware version:
ver             # Firmware version string

# Room server access control:
get acl         # View the room server's access control list
```