Repository navigation
Troubleshooting
"Hydra Flasher is already running"
Another HydraFlasher window is open, possibly on another desktop or hidden behind other windows. Use that one, or close it. On Linux, pgrep -af HydraFlasher lists running instances.
HydraFlasher asks to locate flashprog/flashrom
Neither was found on your PATH. Install flashprog (recommended) or flashrom, or point HydraFlasher at the binary once; the choice is remembered.
● /dev/ttyACM0 · not responding (yellow), or "The Pico on … doesn't answer"
The port looks like HydraFlasher's, but the Pico on it doesn't answer: it runs other or older firmware, or its firmware hangs. HydraFlasher stops asking it for a while (and tries again every 30 s), and refuses jobs on it, so the window stays usable. To fix it, install HydraFlasher firmware: unplug the Pico, hold its BOOTSEL button while plugging it in, then settings → latest or from file…. A Pico that hangs can't restart itself into its bootloader, which is why the button is needed.
○ no programmer stays red
The Pico isn't detected. Check the cable (some cables are charge-only), and check that the Pico runs the HydraFlasher firmware (see Installation). Press ↻ to list all serial ports.
Dropping a file on the window does nothing
Drag and drop needs the optional tkinterdnd2 package: pip install tkinterdnd2, then restart HydraFlasher. When it works, the socket header reads drop an image to write.
Buttons that open a file (write, verify, read, firmware from file…) do nothing A bug in the 1.0.0 AppImage: the system's file dialog (kdialog) couldn't start inside it. Fixed in 1.1.0: download it. With 1.0.0, drag the file onto a socket card or the log instead.
The AppImage doesn't start (fuse: failed to exec fusermount, Cannot mount AppImage)
An AppImage needs FUSE to start. Install it (sudo apt install fuse3 on Debian/Ubuntu, fuse3 on other distributions too), or start it with ./HydraFlasher-*.AppImage --appimage-extract-and-run, which needs no FUSE.
No desktop notification when a job ends
Notifications (and the highlighted taskbar entry) only appear while the HydraFlasher window isn't focused, and not for a successful probe. Check that they're on in settings; on Linux the settings page says needs notify-send (libnotify) when that program is missing.
Desktop notifications stay on screen Also the 1.0.0 AppImage: its notifications never closed by themselves. Fixed in 1.1.0, which closes them after 6 seconds. Notifications can be switched off in settings.
All three LEDs on the Pico stay lit The LEDs are still wired to GP11 to GP13, where older firmware had them. Those pins are chip selects now; move the LEDs to GP16 / GP17 / GP18 (see Updating from older firmware).
The programmer's firmware has 6 CS lines, but "sockets" is …
The Pico runs older firmware with six chip selects. Flash the current firmware (see Installation), or lower sockets to 6. Until then, jobs on the extra sockets are refused with CS*n* has no CS line in the programmer's firmware.
"Sudo required" every time
Your user can't open the serial port. Add yourself to dialout (or uucp on Arch) and log in again. See Installation.
Programmer error: command 0x22: NAK (or another command number, or "no answer")
The Pico's answer wasn't what HydraFlasher expected. Almost always, another program is using the same serial port at the same time: a second HydraFlasher (prevented in current versions), a serial terminal, or flashprog started by hand. Close the other program, unplug and replug the Pico, and try again.
"Multiple flash chip definitions match" Several flashprog definitions fit the chip. Pick the one printed on the chip in the dialog. See Chip Detection.
Probing ALL shows a socket as empty, but probing it alone finds the chip
Older versions probed every socket with the same chip definition, which a chip of another type doesn't match. Current versions pick the definition per socket. If flashprog still finds nothing where the scan sees a chip, the socket keeps its card and the log says CSn: flashprog found no chip, but the scan reads JEDEC …. Reseat the chip, or probe it on its own.
Card shows unsupported chip
flashprog has no definition for this chip. Reseat the chip first: a badly seated chip can return a wrong ID. See Chip Detection.
"Probe required – No chip known on CSn" HydraFlasher doesn't know the chip in that socket yet. Insert one, wait a second for the scan, or press probe. Under sudo the live scan is off, so probe first.
"Size mismatch" The image isn't the same size as the chip. Truncating or padding writes a copy, never your original. If you're not sure the image belongs to this chip, cancel.
"The chips in the sockets are not the same type!" / ALL card says chip types differ
A broadcast (ALL) write or erase needs identical chips, so the write and erase buttons are greyed out while ALL is selected. For the same image on mixed chips, tick one-by-one; for different images use single sockets and the queue.
The write or erase button is greyed out ALL is selected and the chips can't be written or erased all at once: their types differ, one is unsupported, or no chips are inserted. Click the button to see which. Tick one-by-one to handle the chips in turn, select a single socket, or fix the chips.
A queued job failed with "No chip on CSn – nothing written." or "Image is … but CSn is … – nothing written." When the job's turn came, the socket was empty or held a chip of a different size. Insert the right chip and start the job again.
Verify fails (✕ MISMATCH)
- Write the chip again.
- Lower the speed (for example 8M). Long wires and adapters limit the SPI clock.
- Reseat the chip and check the socket's contacts.
- Make sure you verify against the image you wrote. If it was padded or truncated, pick the same original: verify pads or truncates it the same way.
A write was stopped or failed halfway The chip is partially programmed. Write it again.
Chips seem to be inserted and removed on their own The live scan reads garbled IDs, usually because of long wires or a loose adapter. Lower live scan → at on the settings page (for example to 2M), or turn the scan off.
A socket shows not wired, or the wrong number of sockets appears
The socket count comes from the pull-up resistors on the CS lines. A socket without one isn't detected: check that a 10 kΩ resistor connects its /CS line to 3V3 (not to GND, and not in series with the CS wire), then detect again on the settings page. To ignore the detection, pick the count by hand there instead of auto. See Socket count.
"No pull-up resistors found on the CS lines: socket count switched to manual" The Pico didn't detect any pull-up resistor, so the socket count is set by hand now. If your board has them, check that their common line goes to 3V3 (Pico pin 36), then detect again on the settings page switches back to auto. If it doesn't have them, nothing to do: the manual count is used.
The settings say the firmware can't detect (needs 1.2)
Detecting the sockets needs firmware 1.2 or newer: install it from the settings page. Until then the otherwise count is used.
The LEDs on the Pico stay dark Check status LEDs on the settings page, and that the LEDs are wired to GP16 / GP17 / GP18 (see Pinout).
After a firmware update with app 1.0.0, the Pico isn't found again Firmware 1.3 has a new USB ID, which app 1.0.0 doesn't look for while the Pico restarts. The update itself worked: restart the app, or better, update the app to 1.1.0.
… doesn't match the checksum GitHub lists for it (damaged download?) – not installed
The downloaded firmware differs from the file in the release: the download was damaged or altered on the way. Nothing was copied to the Pico. Try latest again; if it keeps failing, download the .uf2 from the release page and use from file….
"… can't be installed: not a UF2 file" or "… made for another chip"
The file isn't firmware for the Pico (RP2040). Use the .uf2 from a release or from firmware/build/.
"… doesn't look like HydraFlasher firmware"
The .uf2 is for the Pico, but not HydraFlasher firmware. Only install it if you know what it is: HydraFlasher may not be able to use the Pico afterwards. To go back, install HydraFlasher firmware the same way (the Pico shows up as RPI-RP2 when you hold BOOTSEL while plugging it in).
Hold the BOOTSEL button on the Pico while you plug it in again…
HydraFlasher couldn't restart the Pico itself (firmware too old, or no direct access to the port). Unplug the Pico, hold its BOOTSEL button, plug it in, then release the button.
"the Pico's bootloader drive (RPI-RP2) didn't show up"
The Pico didn't appear as the RPI-RP2 drive in time. Try again with BOOTSEL as above. On Linux, check that udisksctl works (it mounts the drive).
"The Pico didn't come back as a HydraFlasher serial port"
The copy finished but no HydraFlasher serial port appeared. Unplug the Pico and plug it in again. If it shows up as RPI-RP2 again, the file wasn't accepted; try another download.
"The Pico reports …, not …" The Pico runs a different version than the file: the copy didn't take. Update again.
couldn't check: … next to latest release
GitHub couldn't be reached (offline, proxy, rate limit). check again later; from file… works without the internet.
| Message | Meaning |
|---|---|
Probing is not available during queue run. |
Probing waits until the queue is done; the sockets are scanned between jobs anyway |
Already running or queued: … |
That exact job is already running or waiting, so it wasn't added twice |
Chip override … doesn't fit (…) – reset to Auto-detect |
A chip was inserted that the override doesn't fit, so the override was cleared |
Identify unknown chip on CS*n* |
An automatic probe that learns a new chip type |
Wait for the running/queued jobs first. |
Production mode can't be turned on while jobs run or wait |
Config "sockets": … is not a number from 1 to 10 – using 4. |
The sockets value in the settings file is invalid; see Socket count
|
The firmware can only be updated while no job runs or waits. |
Wait for the queue, then update |
The socket count can't change while jobs run or wait, or in production mode. |
Change it once the queue is empty |
Drop a single image file. |
A folder or several files were dropped; drop one image |
Drop the image on a socket card to write it, or on the log to verify the target. |
The file was dropped somewhere else in the window |
Production mode: the batch image is fixed, the drop is ignored. |
Drops don't change the production image; untick production mode first |
When you report a problem, include the app version and the Pico's firmware version from the settings page.
The log shows every flashprog command HydraFlasher ran (lines starting with $). Select the command and press Ctrl+C to copy it, then run it yourself in a terminal; that often gives more detail. Close HydraFlasher first, so the two don't share the port.
To ask someone for help, right-click the log → Copy all and paste the whole log into your message.