# Flashing Troubleshooting

## Flashing Troubleshooting

Most flashing failures fall into a small set of categories. Work through this table before assuming the device is damaged.

### Troubleshooting Table

<table id="bkmrk-symptomlikely-causef"><thead><tr><th>Symptom</th><th>Likely Cause</th><th>Fix</th></tr></thead><tbody><tr> <td>Device not detected by browser or OS</td> <td>Charge-only USB cable; wrong USB port; missing drivers</td> <td>Try a different cable (data-capable); try a different USB port; install CH340 or CP2102 drivers; try a different computer</td></tr><tr> <td>Device detected but flash fails immediately</td> <td>Not in bootloader mode</td> <td>Hold BOOT while connecting (ESP32) or double-tap reset (nRF52); consult device-specific instructions</td></tr><tr> <td>Device won't boot after flashing</td> <td>Wrong firmware build selected</td> <td>Verify you selected the correct device in the flasher; re-flash with correct build</td></tr><tr> <td>Flashed wrong variant (e.g., Repeater instead of Companion)</td> <td>User error</td> <td>Re-flash with correct variant; no permanent damage</td></tr><tr> <td>ESP32 completely unresponsive / "bricked"</td> <td>Corrupted flash</td> <td>Hold BOOT button → connect USB → run: `esptool.py --port COM3 erase_flash` (substitute your actual port, e.g. `/dev/ttyUSB0` on Linux or `/dev/cu.usbserial-*` on macOS) → re-flash firmware. On newer installs the command may be `esptool` or `python -m esptool`; run `pip install esptool` first.</td></tr><tr> <td>nRF52 unresponsive</td> <td>Corrupted firmware</td> <td>Double-tap reset button to enter DFU mode → reflash via DFU</td></tr><tr> <td>Linux: "Permission denied" on /dev/ttyUSB0</td> <td>User not in dialout group</td> <td>`sudo usermod -a -G dialout $USER` then log out and back in</td></tr><tr> <td>Linux: Web flasher cannot connect</td> <td>udev rules / ACL issue</td> <td>`setfacl -m u:$USER:rw /dev/ttyUSB0`</td></tr><tr> <td>macOS: Device not appearing in /dev/</td> <td>Missing USB-serial driver (depends on the board's USB chip)</td> <td>Identify the chip first. CH340/CH9102 boards: install `CH34xVCPDriver` from wch.cn (or the Homebrew formula). CP210x boards (many Heltec/older devices): install the Silicon Labs CP210x VCP driver. Newer boards with native USB (nRF52 DFU, ESP32-S3 native CDC, e.g. Heltec V4) need no driver and enumerate as `/dev/cu.usbmodem*`. Recent macOS bundles some drivers, but a missing-device symptom usually means the matching VCP driver is not installed.</td></tr><tr> <td>Flash completes but device shows wrong region or settings</td> <td>Old config preserved in flash</td> <td>Perform a factory reset via the app or by flashing with "erase before flash" option checked</td></tr></tbody></table>

### esptool.py Emergency Erase

If an ESP32 device is completely unresponsive and normal bootloader entry fails:

```
pip install esptool
esptool.py --port COM3 erase_flash # Windows
esptool.py --port /dev/ttyUSB0 erase_flash # Linux
```

After erasing, the chip will be blank. Re-flash the firmware normally via the web flasher. (On newer esptool installs the command may be invoked as `esptool` or `python -m esptool` instead of `esptool.py`.)

### Identifying Your Serial Port

**Windows:** Device Manager → Ports (COM &amp; LPT) → look for CH340 or CP210x device. Note the COM number (e.g., COM5).

**Linux:** Run `ls /dev/tty*` before and after plugging in the device. The new entry is your device (typically /dev/ttyUSB0 or /dev/ttyACM0).

**macOS:** Run `ls /dev/cu.*`. Look for cu.usbserial-\* or cu.wchusbserial\*.