Troubleshooting¶
I installed openFPGALoader but it says command not found when I try to launch it¶
The correct spelling of the program is openFPGALoader with FPGA and the "L" of "Loader" in uppercase. Ensure the spelling of the program is correct.
Gowin device could not communicate since last bitstream flashed. (issue #206)¶
Gowin's FPGA may fails to be detected if JTAGSEL_N (pin 08 for GW1N-4K) is used as a GPIO. To recover you have to pull down this pin (before power up) to recover JTAG interface (UG292 - JTAGSELL_N section).
JTAG init failed¶
Avoid using USB hubs and connect it directly to your PC USB port.
MachXO3LF JEDEC fails with UFM section out of bounds¶
On MachXO3L/MachXO3LF, .jed files program the internal NVCM/Flash through the Lattice JTAG/ISC command flow. A --bridge bitstream is not required for this operation.
If programming reaches JEDEC parsing and then stops with:
UFM section detected in JEDEC file, but calculated flash start address was out of bounds
check the verbose log just before the error. A typical affected MachXO3LF-9400C file may show:
JTAG chain: [0]=0x612be043
family MachXO3LF
model LCMXO3LF-9400C
NOTE TAG DATA
L2063488
MachXO3 JEDEC files can contain NOTE TAG DATA sections for NVCM1/UFM pages. For a 9400 device, 2063488 / 128 is page 16121, the documented total CFG+UFM page count. If that section is all zero, it is a trailing empty tag block emitted by Diamond and should be skipped rather than programmed as UFM payload.
Use a version of openFPGALoader that includes the MachXO3 9400 UFM page map and skips empty out-of-range TAG DATA blocks. If you still see the error with a non-empty TAG DATA section, regenerate the JEDEC from Diamond and verify the selected device density/package matches the physical FPGA reported by openFPGALoader --detect.
SPI flash RDID 0x77b80a / Macronix MX77L25650F¶
RDID 0x77b80a has been observed on targets using a Macronix MX77L25650F-class flash. Public flashrom/Chromium flash databases list the canonical Macronix MX77L25650F JEDEC RDID as 0xc27519 and the chip as 256 Mbit / 32 MiB.
openFPGALoader maps both IDs to the same 32 MiB flash definition, so full auto-sized dumps are supported:
openFPGALoader -c ft2232 --dump-flash dump.bin
If possible, verify the physical package marking. A board reporting 0x77b80a may indicate a transport/readback quirk rather than the canonical JEDEC RDID.
Tang Primer 20k program slow and stucked (issue #250)¶
Check your openFPGALoader version:
openFPGALoader -V
If it is older than release then v0.9.0, install the most recent version (from commit f5b89bff68a5e2147404a895c075773884077438 or later).
Cannot flash Tang Nano 20k (issue #251)¶
Some firmware version cannot be flashed on Linux-based systems. Version 2024122312 is such an example. It seems this version was not published on the SiPeed website, however some boards sold have this firmware.
The cause of the problem is the debugger on the Tang Nano, specifically the firmware of this debugger. This firmware can be easily updated by following these steps.
Cannot flash Tang Nano 9k (issue #251)¶
This is a device issue, erase its Embedded Flash using Official GoWin Programmer (preferentially in Windows) and SRAM too, then you can use openFPGALoader again.
Unable to open FTDI device: -4 (usb_open() failed) (issue #245)¶
Edit your /etc/udev/rules.d/99-ftdi.rules file exchanging your programming device permissions.
For more information, check the udev section from this guide
Converter cannot be opened: fails to open device (issue #626)¶
This is usually a permissions issue on Linux.
Check your current groups:
id $USER
Verify device node access rights:
ls -l /dev/ttyUSB* /dev/ttyACM*
Then verify udev rules are installed correctly (70-openfpgaloader.rules or 99-openfpgaloader.rules), and that your user is in the expected group (dialout or plugdev).
After changing groups or rules, reload udev rules, then unplug/replug the converter and log out/login again.
Reference: install guide (udev rules section).
Unable to flash device on OpenBSD: JTAG init failed with: DirtyJtag: fails to open device¶
Certain evaluation boards may show the following error message when running openFPGAloader on OpenBSD:
fail to read data usb bulk read failed
JTAG init failed with: low level FTDI init failed
This issue is most likely caused by the uftdi(4) module, which has attached itself to the device, whereas openFPGALoader requires it to be accessible as a ugen(4) device.
Unfortunately, due to the security concept of OpenBSD, it is not possible to detach it without modifying the kernel and rebooting the system. However, there are two ways to resolve the issue: Either by patching and recompiling the kernel; or by deactivating the uftdi(4) module.
After COMMENTING OUT the problematic devices in /usr/src/sys/dev/usb/uftdi.c, the code would look like this:
{ USB_VENDOR_FTDI, USB_PRODUCT_FTDI_SEMC_DSS20 },
//{ USB_VENDOR_FTDI, USB_PRODUCT_FTDI_SERIAL_2232C },
{ USB_VENDOR_FTDI, USB_PRODUCT_FTDI_SERIAL_2232L },
With this manual patch applied, follow the OpenBSD custom kernel guide to recompile the kernel.
Without recompilation, DEACTIVATING uftdi(4) can be achieved using the following commands:
# doas config -e -f -o /bsd.nouftdi /bsd
OpenBSD 7.8 (GENERIC) #54: Sun Oct 12 12:45:58 MDT 2025
deraadt@amd64.openbsd.org:/usr/src/sys/arch/amd64/compile/GENERIC
Enter 'help' for information
ukc> disable uftdi*
356 uftdi* disabled
ukc> disable uftdi0
ukc> disable uftdi1
ukc> quit
Saving modified kernel.
# reboot
At the boot prompt, typing in
boot> boot /bsd.nouftdi
will boot the new kernel with the disabled module.
Either way, openFPGALoader will then be able to access the development board as a generic USB device via ugen(4).