Troubleshooting

Meshtastic Guides

The board does not show up over USB

• Swap the cable first. Charge-only USB cables cause more "dead board" reports than dead boards do.
• Check dmesg | tail for the port. Nothing at all: cable or board. Appears then vanishes: brltty is stealing it (see Flashing).
• Permission denied on /dev/ttyACM0: add yourself to dialout and re-login.

The flasher cannot enter the bootloader

• ESP32: hold BOOT while plugging in (or while tapping reset), then flash.
• nRF52: double-tap reset. A USB drive appears; copy the UF2 onto it. If the drive never appears, adjust the double-tap rhythm and try again; it is fussier than it should be.

The node will not transmit

If the region is unset, the radio stays silent by design. Set the region. This is the single most common "it does not work" on a fresh flash.

The app cannot connect over Bluetooth

• One client at a time: a node connected to another phone or an open CLI Bluetooth session will not take a second connection.
• Pairing PIN: boards with a screen display the PIN to enter; screenless boards use the documented default (123456).
• After firmware updates or failed pairing loops, remove the node from the phone's system Bluetooth list and pair fresh from the app.

You hear nobody

• Region or modem preset mismatch: both must match the local mesh. A node on a nonstandard preset is invisible even at zero distance.
• Confirm the antenna is attached, snug, and built for your band (868/915 vs 433 antennas are not interchangeable).
• Check MeshMap: there may genuinely be nobody in range. Radios cannot fix demographics.
• Get elevation: even second-story height changes what you can hear (see Range Expectations).

Nodes appear from absurdly far away

That is not radio, that is MQTT: somebody in your mesh has internet downlink enabled and is injecting remote traffic. See the MQTT section of the Configuration guide. Check a node's hops and SNR before concluding you made a 3000 km LoRa contact.

Messages send but never deliver

• Check the hop count between you and the destination; past the hop limit, packets simply die en route.
• Busy meshes drop and delay traffic; the primary channel in a dense area carries everyone's telemetry too.
• The node list remembers nodes it has not heard from in days. Last-heard time matters more than presence in the list.

Battery life is terrible

That is almost certainly the chipset, not the firmware: ESP32 boards measure battery life in days, nRF52 boards in weeks. See the Hardware guide before blaming settings.

Where to get help

The official docs are thorough, and the community links on meshtastic.org lead to the forum and chat. Bring specifics: board, firmware version, region, modem preset, and what dmesg or the app actually said. "It does not work" gets the answers it deserves.