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:
 
Is the problem isolated to one node pair, or affecting all nodes?
 
Is the problem one-directional or bidirectional?
 
Did it work before? What changed?
 
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