Skip to main content

Troubleshooting a Misbehaving Repeater

Infrastructure repeaters are expected to operate unattended for months. When behaviour deviates from normal - excessive channel utilisation, duplicate node entries, relay failures, or complete silence - rapid and systematic diagnosis avoids unnecessary site visits and minimises community impact. This page catalogues the most common symptoms, their likely causes, and the remediation steps including serial console diagnostics.

Symptom 1: High Channel Utilisation Caused by This Node

Diagnosis

In the Meshtastic app or web UI, open the node list and check the channel utilisation percentage. If it is above 25% and you suspect a specific node is the primary contributor, run a traceroute from multiple points to see which node rebroadcasts most frequently, or check the MQTT stream for an unusually high publication rate from one node ID.

# On the suspect node: check current telemetry broadcast interval
meshtastic --get telemetry.device_update_interval
meshtastic --get telemetry.environment_update_interval

# Check position broadcast interval
meshtastic --get position.position_broadcast_secs

Common causes and fixes

Short telemetry intervals: If device_update_interval is set to 60 seconds (the minimum), a single node generates one telemetry packet per minute plus the corresponding rebroadcasts. Increase to 30 minutes for infrastructure nodes:

meshtastic --set telemetry.device_update_interval 1800
meshtastic --set telemetry.environment_update_interval 1800

Short position broadcast interval: A fixed repeater broadcasting position every 5 minutes generates 288 position packets per day. Increase to 24 hours:

meshtastic --set position.position_broadcast_secs 86400

Smart broadcast enabled on a non-moving node: Smart position broadcasting transmits whenever the node moves more than a configured distance. On a fixed node, GPS jitter can cause false movement detection and trigger frequent transmissions. Disable it:

meshtastic --set position.position_broadcast_smart_disabled true

Symptom 2: Node Appearing Twice in the Node List

Diagnosis

Two entries in the node list with the same name or similar names, but different node IDs, indicates that the same physical device has been flashed or configured with two different node identities. This typically happens when:

  • A backup config from device A was imported onto device B, causing B to broadcast device A's NodeInfo until B's radio generates its own unique ID advertisement.
  • A node was factory-reset, generating a new node ID, but other mesh nodes still have the old ID cached.
  • Two devices were cloned by copying the flash image directly (not supported - never duplicate node configurations this way).

Remediation

If two physical devices have the same node ID (the critical case - never do this): One device must be factory-reset to generate a new unique ID. Factory reset clears all configuration including channel keys - re-configure from scratch:

meshtastic --factory-reset

If stale entries persist after a legitimate device reset: Other mesh nodes cache node entries and only expire them after the configured node info broadcast interval. The stale entry will disappear on its own once the cache TTL expires. This can take 4 - 8 hours by default. There is no remote command to force-clear another node's cache, but you can clear a specific device's own node DB:

meshtastic --remove-position

Symptom 3: Node Offline Despite Power Being Present

Diagnosis

The node is powered (LEDs lit, no alarm on power supply) but is not appearing in the mesh and is not publishing to MQTT. This indicates a firmware hang, a radio module fault, or a configuration issue that prevents the radio from transmitting.

Step 1: Attempt remote reboot

# From any node with admin channel configured
meshtastic --dest '!abcd1234' --reboot

If the radio stack is functional but the application layer is hung, this may succeed. If the node comes back after a reboot command, enable the hardware watchdog to prevent future hangs requiring manual intervention:

meshtastic --dest '!abcd1234' --set device.watchdog_secs 300

Step 2: Serial console inspection

Connect via USB and open a serial terminal at 115200 baud:

screen /dev/ttyUSB0 115200
# or on macOS:
screen /dev/cu.usbserial-0001 115200
# or using meshtastic CLI:
meshtastic --port /dev/ttyUSB0 --debug

Look for these patterns in the serial output:

  • assert or Guru Meditation Error - firmware crash, followed by register dump. Note the crash address for reporting to the Meshtastic GitHub issues.
  • No packets received in X seconds - radio module may be locked up. Try power cycling.
  • nvs_flash errors - NVS (non-volatile storage) corruption. Full flash erase followed by re-flash and reconfiguration is required.
  • Looping reboot messages without reaching Meshtastic initialised - hardware fault (common with damaged SPI bus between ESP32 and LoRa module).

Step 3: Full power cycle

Disconnect power completely (including USB) for 10 seconds. Many transient LoRa module hang states clear only with a full power cycle, not a software reset.

Symptom 4: Node Not Relaying Packets

Diagnosis

The node appears in the node list and is visible on the map, but traceroutes confirm it is not serving as a relay hop - packets that should transit through it are not being forwarded.

Check the device role

This is the most common cause. A node configured as CLIENT does not relay packets from other nodes. Confirm:

meshtastic --get device.role

If the role returns CLIENT, change it:

meshtastic --set device.role ROUTER

Check the rebroadcast mode

meshtastic --get device.rebroadcast_mode

Valid relay modes are ALL (rebroadcast everything) and ALL_SKIP_DECODING (rebroadcast without decrypting, lower CPU). A mode of LOCAL_ONLY or KNOWN_ONLY restricts which packets are relayed and may explain why transit traffic is being dropped.

Check hop count on arriving packets

If packets arrive at this node with a remaining hop count of 0, they are consumed and not forwarded - this is correct behaviour, not a fault. Verify by enabling debug output and watching the hop_limit field in received packets:

meshtastic --debug 2>&1 | grep "hop_limit"

If all arriving packets have hop_limit = 0, the originating nodes need their lora.hop_limit increased.

Check channel configuration

The repeater must share channel 0 credentials with the nodes it is relaying for. If the PSK does not match, the node cannot decode the packet to check the duplicate-detection hash, and behaviour is undefined (most implementations drop it).

meshtastic --info | grep -A 5 "channel_0"

Serial Console Diagnostic Reference

When physically on-site, the following serial console commands provide rapid triage:

# Full device info dump (version, channels, config, node DB)
meshtastic --info

# Show all current configuration in structured output
meshtastic --export-config

# Watch live packet events (requires --debug flag)
meshtastic --debug

# Check for NVS storage health (ESP32 only, via monitor output)
# Look for: "NVS Stats: used=X, free=Y" - free should be > 20%
# Low free NVS can cause intermittent config save failures

# Factory reset if NVS corruption is confirmed
meshtastic --factory-reset

Reading the debug log for relay events

When --debug is active, relay events appear as lines like:

Rebroadcasting packet from !abcd1234, hopLimit=2
Ignoring duplicate packet from !abcd1234 (id=0x12345678)

If you see only Ignoring duplicate packet lines and no Rebroadcasting lines, the node is receiving packets but treating them all as duplicates. This can happen if the duplicate detection window (stored in RAM) has stale entries from a previous session - a reboot typically clears this.

If neither message type appears for packets that other nearby nodes are hearing, the LoRa receive path is not functioning. Check antenna connection (a disconnected antenna is the single most common field repair) and SPI bus integrity.

No comments to display

Back to top