The following page provides suggestions for common errors that may occur during firmware compilation. If the information provided is insufficient to resolve the issue, feel free to seek out help from the ZMK Discord.
File Transfer Error
Variations of the warnings shown below occur when flashing the
<firmware>.uf2 onto the microcontroller. This is because the microcontroller resets itself before the OS receives confirmation that the file transfer is complete. Errors like this are normal and can generally be ignored. Verification of a functional board can be done by attempting to pair your newly flashed keyboard to your computer via Bluetooth or plugging in a USB cable if
ZMK_USB is enabled in your Kconfig.defconfig.
|An example of the file transfer error on Windows 10|
|An example of the file transfer error on Linux|
|An example of the file transfer error on MacOS|
CMake Warnings shown above during
west build are normal occurrences. They should not negatively affect the firmware's ability to function as normal.
On the other hand, an error along the lines of
CMake Error at (zmk directory)/zephyr/cmake/generic_toolchain.cmake:64 (include): include could not find load file: during firmware compilation indicates that the Zephyr Environment Variables are not properly defined.
For more information, click here.
An error along the lines of
dtlib.DTError: <board>.dts.pre.tmp:<line number> during firmware compilation indicates an issue within the
This can be verified by checking the file in question, found in
|An example of the dtlib.DTError when compiling an iris with the nice!nano while the keymap is not properly defined|
After opening the
<board>.dts.pre.tmp:<line number> and scrolling down to the referenced line, one can locate errors within their shield's keymap by checking if the referenced keycodes were properly converted into the correct USB HID Usage ID.
|An incorrectly defined keymap unable to compile. As shown in red, |
|A properly defined keymap with successful compilation. As shown in red, the corrected keycode (|
Split Keyboard Halves Unable to Pair
Previously, pairing split keyboard halves involved a BLE Reset via a combination of held keys that removed all bluetooth profile information from the keyboard. Since then, a much simpler procedure of performing a bluetooth reset for split keyboards has come about, without the need for any file modification:
- Log into Github and download the "settings clear" UF2 image from the latest build in Github Actions
- Put each half of the split keyboard into bootloader mode
- Flash one of the halves of the split with the "settings clear" UF2 image from step 1. Immediately after flashing "settings clear" to the chosen half, immediately put it into bootloader mode to avoid accidental bonding between the halves.
- Repeat step 3 with the other half of the split keyboard
- Flash the actual image for each half of the split keyboard (e.g
my_board_left.uf2to the left half,
my_board_right.uf2to the right half)
After completing these steps, pair the halves of the split keyboard together by resetting them at the same time. Most commonly, this is done by grounding the reset pins for each of your keyboard's microcontrollers or pressing the reset buttons at the same time.