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