Troubleshooting
When something looks wrong
No serial port appears at all
It's the cable. Charge-only USB cables have no data lines and are everywhere. Second
suspects: a USB hub misbehaving (go direct), or on Linux, permissions
(sudo usermod -a -G dialout $USER, re-login).
Port exists, but Coop's handshake times out
- Something else owns the port. USB serial is exclusive — close the Meshtastic
CLI, other dashboards, or a second Coop.
lsof /dev/cu.usbmodem*(macOS) tells you who. - The firmware isn't Meshtastic. Factory demos and Arduino sketches enumerate a port but speak no protocol. Flash real firmware at flasher.meshtastic.org.
- The USB stack is wedged — after port fights or failed flashes a board can stop answering entirely (even esptool sees nothing). Unplug/replug or tap RST; software can't always recover this one.
Connected, but silence
Check region (UNSET radios don't transmit), then antenna, then location — a basement node may legitimately hear nothing. The Radio Check panel in Perch runs this diagnosis; patience matters too, as a quiet mesh can take minutes between packets. Turning on the MQTT observer instantly shows whether the problem is your ears or the neighborhood.
Sent messages show "awaiting ack" then "no-ack"
Broadcasts aren't acked reliably by design; DM acks depend on the destination actually hearing you. "No-ack" after the grace period means the mesh didn't confirm — likely range, not software. A traceroute to the destination tells you if a route exists at all.
Perch says the engine is offline
- Is Coop running? Its status page (
http://127.0.0.1:2667) is the ground truth. - Port clash: Coop may have bound a fallback (6374…) — the status page banner and logs say which; re-probe the host from Perch's engine menu.
- Remote engines: wrong control key gives you observer mode (reads work, writes 403), and
"the network is fine" is a lie until proven with
curl host:2667/api/health.
Log lines that look scary but aren't
| Line | Meaning |
|---|---|
unhandled protobuf from radio | The transport library saw a frame type it doesn't route (config chatter during handshake). Harmless. |
retention purged N rows… | Working as configured. |
handshake failed … (retry in 2s) | Normal during radio reboots (region/channel changes reboot the radio; Coop reconnects itself). |
Where to look when reporting a bug
Coop's log (it prints to stdout; the macOS app logs to Console), the output of
/api/health, and — if it's about a specific packet — the relevant rows from
the capture DB. Issues welcome.