Skip to main content
Pitch In Subscribe

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, runinspect aeach traceroutecandidate fromnode's multiplereported pointsairtime/channel-utilisation telemetry, or watch the serial/debug log of the suspect node to see how often it is transmitting and rebroadcasting. (Traceroute shows the routing path/hops to a destination - it does not measure which node rebroadcasts most frequently, orso it is not the right tool for isolating a chatty node.) You can also 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 ishas setbeen toshortened 60well secondsbelow (the minimum),default, a single node generates onea telemetry packet perevery minuteinterval plus the corresponding rebroadcasts. Increase(Note: a connected client app always receives device metrics once per minute regardless of this setting - that local behaviour is separate from the over-mesh broadcast interval, whose default is 1800 seconds / 30 minutes.) Set it back 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_disabledposition_broadcast_smart_enabled truefalse

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:

Warning: A factory reset erases the channel PSK and all configuration - the node will fall off your mesh and emergency channel until it is manually re-keyed, which on a remote node means a site visit. NEVER factory-reset a sole-path or remote infrastructure node without (a) a current exported config backup (meshtastic --export-config > config.yaml) and (b) physical or admin access to restore it. Do not perform this during an active incident.

meshtastic --factory-reset

If stale entries persist after a legitimate device reset: Other mesh nodes cache node entries and only expire themstale afterones on their own over time - there is no fixed published TTL, but the configured node info broadcast interval. The stale entry will disappearage onout itswithout own once the cache TTL expires. This can take 4 - 8 hours by default.intervention. There is no remote command to force-clear another node's cache,cache. butNote youthat can--remove-position clearonly unsets a specific device's own fixed position (latitude/longitude/altitude) - it does NOT clear the node DB:database. To reset a node's own NodeDB requires either the dedicated NodeDB-reset command or a factory reset; clearing a node's own DB does not remove a stale entry that other nodes are caching, which simply expires on its own.

# Clears only this device's own fixed position - NOT the node database:
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 recovery

Remote administration over --dest supports only the --set and --get commands - there is no supported remote --reboot command, so a hung node generally cannot be rebooted over the air. You can remotely read or adjust settings if the radio stack is still responding:

# From any node withRemote admin channelsupports configuredonly --get / --set over --dest:
meshtastic --dest '!abcd1234' --rebootget device.role

If the radio stack is functional but the application layer is hung, thisremote reads may succeed.still respond. If the node comesis backfully afterunresponsive, you will need a rebootphysical command,power enablecycle theor hardwareserial console access (below). Meshtastic has no configurable hardware-watchdog setting to prevent future hangs requiring manual intervention:enable.

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:output (exact log wording varies by firmware version):

  • assert or Guru Meditation Error - firmware crash, followed by register dump. Note the crash address for reporting to the Meshtastic GitHub issues.
  • NoMessages indicating no packets are being received in- X seconds -the 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 the firmware reaching Meshtastica initialisedcompleted-boot state - this can indicate a hardware faultfault; (commonone withpossible cause is a damaged SPI bus between the ESP32 and the LoRa module).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 CLIENTCLIENT_MUTE does not relay packets from other nodes. Confirm:A plain CLIENT node DOES relay - it rebroadcasts packets when no other node has already done so - so a CLIENT role is not, by itself, the reason a node fails to forward. Confirm the role:

meshtastic --get device.role

If the role returns CLIENTCLIENT_MUTE (which suppresses rebroadcasting), change it:it. For a well-placed stationary infrastructure node, ROUTER is the recommended role:

meshtastic --set device.role ROUTER

Check the rebroadcast mode

meshtastic --get device.rebroadcast_mode

ValidThe relayrebroadcast modesmode areis set under the device. namespace (device.rebroadcast_mode). The valid values are:

    ALL (- rebroadcast everything)all andpackets (the default). ALL_SKIP_DECODING - same as ALL but skips packet decoding and simply rebroadcasts. This only takes effect on the REPEATER role; it is not a general relay mode for other roles. LOCAL_ONLY - ignore packets from foreign meshes (other regions/modem presets), relaying only local-mesh traffic. KNOWN_ONLY - relay only packets from nodes already in the NodeDB, filtering out unknown/foreign nodes. NONE - do not rebroadcast without(only decrypting,valid lowerfor CPU)SENSOR/TRACKER/TAK_TRACKER roles). CORE_PORTNUMS_ONLY - rebroadcast only core protocol port numbers.

    A mode of LOCAL_ONLY or KNOWN_ONLY restrictsfilters whichforeign-mesh packets are relayedtraffic and may explain why some 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 may need their lora.hop_limit increased.increased (default 3, maximum 7). Raising the hop limit increases airtime and can worsen congestion, so do this cautiously and watch channel utilisation.

    Check channel configuration

    TheA repeaterrelay mustforwards sharepackets based on the unencrypted packet header (sender NodeID + packet ID), and it deduplicates using that same header - so a node can and does rebroadcast packets even when it does not hold the channel 0PSK. credentialsThis is exactly why ALL_SKIP_DECODING can relay channels it cannot decrypt. A PSK mismatch prevents reading the message content, not relaying it. To actually exchange and read messages with the nodes ityou isare relaying for. Ifserving, the channel 0 PSK doesmust not match, the node cannot decode the packet to check the duplicate-detection hash, and behaviour is undefined (most implementations drop it).match:

    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

# ShowExport allthe full current configuration into structureda outputYAML backup file
meshtastic --export-config > config.yaml

# 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(last NVSresort corruption- iswipes confirmedconfig and channel keys; back up first)
meshtastic --factory-reset

    Reading the debug log for relay events

    When --debug is active, relay events appear asin linesthe like:log. The exact wording varies by firmware version, but conceptually you will see rebroadcast events (the node forwarding a packet with a decremented hop limit) and duplicate-suppression events (the node ignoring a packet it has already heard), for example:

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

    If you see only Ignoring duplicate packetduplicate-suppression lines and no Rebroadcastingrebroadcast 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.

    Back to top