Troubleshooting Guide
Common issues and solutions for firmware flashing with Flashie.
No serial port is listed
- Ensure your board is connected via a USB data cable (not a charge-only cable).
- Install the appropriate USB-to-serial driver (CH340, CP2102, or FTDI).
- Check Device Manager (Windows) or run lsusb (Linux/Mac) to see if the device is detected.
- Try a different USB port on your computer.
- Restart your browser and try again.
Flashing starts but fails mid-way
- Your board may have exited bootloader mode. Re-enter bootloader mode and try again.
- The USB cable may be unstable. Try a shorter or higher-quality cable.
- Close other applications that might be using the serial port (Arduino IDE, serial monitors).
- Try a different USB port (preferably USB 2.0).
Failed to download manifest.json
- Verify the manifest URL is correct by opening it directly in your browser.
- Ensure the manifest file exists in the public/projects/ directory.
- If using GitHub Pages, wait for the deployment to complete (can take 2-3 minutes).
- Clear your browser cache and perform a hard refresh (Ctrl+F5).
- Check that the file paths use the correct case (GitHub Pages is case-sensitive).
Flash button says 'Browser not supported'
- Switch to Google Chrome or Microsoft Edge (version 89 or later).
- Update your browser to the latest version.
- Mobile browsers do not support the Web Serial API. Use a desktop/laptop computer.
Flash button says 'HTTPS required'
- Access Flashie via HTTPS or localhost.
- If running locally, use http://localhost instead of http://127.0.0.1.
- For remote access, ensure your site is served over HTTPS.
ESP32 not entering bootloader mode
- Hold the BOOT button, press EN once, then release BOOT — timing matters.
- Some ESP32 dev boards have an auto-reset circuit. Try pressing BOOT alone while the flash begins.
- Check that the BOOT button is connected to GPIO0 (not EN).
- Try connecting GPIO0 to GND manually with a jumper wire.
Troubleshooting
Failed to download manifest
This error occurs when the manifest.json file cannot be fetched. Verify the manifest URL in your project configuration points to the correct file path. Check that the file exists in the public/projects/<project>/ directory and that GitHub Pages has deployed the latest changes. Clear your browser cache and try again.
Flashing connection failures
Connection failures usually mean the board is not in bootloader mode. For ESP32, hold the BOOT button, press EN, then release BOOT. For ESP8266, connect GPIO0 to GND before powering on. Also check that you selected the correct serial port and that no other program (like Arduino IDE) is using it.
GitHub Pages 404 errors
404 errors on GitHub Pages often indicate incorrect file paths. Ensure your manifest.json path starts with a forward slash and points to the correct location under the public/ folder. Remember that GitHub Pages is case-sensitive. File paths in manifests and firmware references must match exactly.
Incorrect firmware paths
Firmware paths in the manifest.json are relative to the manifest file location. For example, if your manifest is at /projects/my-project/manifest.json and firmware is at /projects/my-project/firmware/firmware.bin, the path in manifest should be firmware/firmware.bin (not absolute).
Browser cache issues
Outdated cache can cause stale manifests or firmware to be served. Perform a hard refresh (Ctrl+F5 or Cmd+Shift+R) to bypass the cache. Alternatively, open DevTools, go to the Network tab, and check 'Disable cache'. For persistent issues, clear all site data in Chrome settings.
USB driver problems
Many ESP32/ESP8266 boards use CH340 or CP2102 USB-to-serial chips. Windows may need drivers: download CH340 drivers or CP2102 drivers from the manufacturer. On macOS and Linux, these usually work out of the box. For STM32 boards, you may need the Zadig tool to install WinUSB drivers for DFU mode.