MeshCore network troubleshooting
Debug tools, log analysis and practical solutions for MeshCore problems
Solving network problems
Even with a well-configured MeshCore network, problems can occur. Nodes that won't connect, messages that don't arrive, short range or high battery drain - these are common issues you may encounter.
This troubleshooting guide helps you systematically identify and solve problems. We cover the most common issues, debug tools you can use and step-by-step solutions.
MeshCore has extensive logging and diagnostics built-in that let you see exactly what's happening. By using these tools and following a structured approach, you can solve most problems yourself.
Common problems and solutions
1. Node won't connect to network
Your node stays "searching" or shows no other nodes in the list.
Solution:
Check configuration: Make sure you're on the same frequency (868 MHz) and channel as the network. Also check your region settings (should be EU for Netherlands). Verify your antenna is properly attached and not damaged.
2. Messages don't arrive
You send messages but receivers don't get them.
Solution:
Check range: Are you within radio range? In urban areas this is ~1km, in open field up to 10km. Also check your transmit power settings - maybe it's too low. Look in the logs whether messages are routed via repeaters.
3. Very short battery life
Your battery is empty within hours instead of days.
Solution:
Reduce power usage: Set transmit power lower (10-15dBm is often enough). Increase the broadcast interval from 15 to 30-60 minutes. Disable Bluetooth if you're not using it. Use sleep mode between messages.
4. Poor signal quality (SNR)
Messages are received but with low SNR (Signal-to-Noise Ratio).
Solution:
Improve antenna setup: Use a better antenna (5dBi or higher). Place your node higher (minimum 2 meters above ground). Remove obstacles between nodes. Check if your antenna is properly tuned to 868 MHz.
5. Node reboots spontaneously
Your node restarts itself randomly, without clear cause.
Solution:
Power and firmware issues: Check your power supply - use minimum 500mA USB adapter. Update to the latest firmware version. Check the serial logs for crash reports. Possibly your hardware is defective - test with another node.
Debug tools for troubleshooting
Use these tools to see exactly what's happening in your mesh network
Serial monitor
Real-time logs via USB connection - see all events, errors and debug output
MeshCore app
Node list, signal strength, message history and configuration in one app
Web interface
Browser-based config and monitoring for advanced diagnostics
Python CLI
Command-line tool for scripting, automation and bulk operations
MQTT monitoring
Real-time network data to MQTT broker for logging and visualization
Log analysis tools
Parse and analyze log files to identify patterns and problems
Diagnostic commands
Use these commands via CLI or serial monitor to diagnose your network
Show network nodes
See all nodes your node can detect with their SNR and distance:
Check radio statistics
View radio metrics like transmit power, air utilization and packet stats:
Test connectivity
Send a test message to a specific node and measure latency:
Dump configuration
Export all settings to JSON to check configuration:
Troubleshooting checklist
-
☐
Firmware version: Update to latest stable release
-
☐
Frequency settings: 868 MHz for Europe (not 915 MHz)
-
☐
Region settings: EU for Netherlands, not US or other region
-
☐
Channel configuration: Same channel and encryption key as network
-
☐
Antenna: Properly connected, 868 MHz tuned, no damage
-
☐
Power supply: Minimum 500mA, stable voltage, good cable
Frequently asked questions
How do I see the debug logs from my node?
Connect your node via USB and open a serial monitor (Arduino IDE, PlatformIO or screen/minicom on Linux). Baud rate is 115200. You'll see real-time logs of all events.
What does a low SNR value mean?
SNR (Signal-to-Noise Ratio) indicates signal quality. Above +5 dB is good, -5 to +5 dB is moderate, below -5 dB is poor. Low SNR means messages often fail or get corrupted.
My node sees nodes but can't communicate, why?
This can be due to incorrect encryption settings. Check if your encryption key matches the channel you're trying to communicate on. Also firewall rules or channel access restrictions may block you.
How do I reset my node to factory settings?
Use the command meshcore --factory-reset via CLI, or press the reset button on your device for 10 seconds. Warning: all configuration and messages will be erased!
Where can I find help if I can't figure it out myself?
Join the MeshCore Telegram group at t.me/meshcorenet. The community is happy to help with troubleshooting. Post your logs and configuration for faster help.
Need help with troubleshooting?
The MeshCore community is ready to help you with network problems
Share your logs and ask for advice - together we'll solve it!