Troubleshooting

MeshCore 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, try the double-tap rhythm again: it is fussier than it should be.

The app cannot connect over Bluetooth

• BLE allows one active client. A companion already connected to another phone, tablet, or a running meshcore-cli BLE session will not accept a second connection. Disconnect the other client.
• After firmware updates or re-pairing loops, remove the device from the phone's system Bluetooth list and pair fresh from the app.

You hear nobody

• Region preset mismatch is the first suspect. Frequency, bandwidth, and spreading factor must all match the local mesh. Custom settings make you invisible.
• Confirm the antenna is attached, snug, and built for your band (868/915 vs 433 antennas are not interchangeable).
• Check the map: there may genuinely be nobody in range. Radios cannot fix demographics.
• Send a flooded advert, then get elevation: even second-story height changes what you can hear (see Range Expectations).

Direct messages fail but the channel works

Channel traffic floods; direct messages follow a learned path through specific repeaters. If a repeater on that path went away, DMs can fail while broadcast traffic still arrives. Send a fresh flooded advert from both ends so the path gets relearned, and confirm the repeaters between you are actually up.

Timestamps are wrong

A node's clock is wrong, usually a repeater or room server after a power outage (companions sync from the phone). Set the clock over remote admin or meshcore-cli. If a site loses power regularly, clock-sync-after-outage belongs on the checklist.

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 and the community links on meshcore.io are the places to ask. Bring specifics: board, firmware role and version, region preset, and what dmesg or the app actually said. "It does not work" gets the answers it deserves.