gpu unlock error -2: gpu_unlock firmware load failed because the payload is missing

What gpu unlock error -2 means

Two lines in dmesg, and the first one names the stage that failed.

NVRM: GPU 0000:01:00.0: Failed to load firmware
nvidia: probe of 0000:01:00.0 failed with error -2

That is the gpu_unlock firmware load failed case in its simplest form: the module ran, but the payload was absent. Failed to load firmware is the driver's firmware loader giving up. -2 is ENOENT unwinding out of the probe: the driver reached for a file, the path was empty. Neither line claims the card is unsupported, and neither one means the module is missing. [issue #67]

Compare that with a -16 log, whose first line is RmInitAdapter failed and whose code is EBUSY. There the device had an owner before firmware was ever on the table. The first line of the log separates the two faster than the code does, which matters because the fixes have nothing in common.

So the useful question is not why the card failed. It is which build produced the image you are booting, and whether that build put the payload in.

Why gpu unlock firmware is a build-time problem

The project does not ship a firmware blob you can copy. The build downloads inputs from NVIDIA and CachyOS and generates the firmware as part of the same run, writing it into the build directory and into the binary package. The inputs are cached at ~/.cache/gpu-unlock/inputs; make inputs fetches them, and INPUTS= points the build at a different cache. [official README]

That single fact explains most of the confusion around gpu_unlock firmware load failed reports. A source package is source: make dist, the Debian source package and the .nosrc.rpm carry neither the NVIDIA archives nor the generated firmware, so nothing is lost when one of them is missing from the tree.

Install from source on the machine and the firmware is generated there. Install from a binary package and it was generated when the package was built. Skip either step and you get a module that loads and a payload that does not exist.

There is also no separate firmware package to fetch, and the reason is licensing rather than neglect. The kernel module and the local packaging are GPL-2.0-only, the CMP reference is MIT, and the generated firmware stays under NVIDIA's own terms, which the repository states in firmware/NOTICE.md. [official README]

Anyone offering a blob download for this is redistributing something the project deliberately does not.

If you have been copying a file out of another kernel's tree, that is the second -2 after a clean reinstall explained. A blob from a different build is not the file this build expects, and the probe that cannot find its own payload fails the same way as one that finds nothing at all.

Look for gpu unlock inside the image

The image you boot is where the answer is, and it is readable before you change a thing.

lsinitramfs /boot/initrd.img-$(uname -r) | grep -E 'gpu_unlock\.ko|firmware'

Three shapes come back, and they point in different directions.

• No output at all. Neither gpu_unlock.ko nor a firmware entry matched. The module most likely never entered the image; check the generator before treating this as a payload problem. The companion page on -16 explains that branch.
• The module is listed, but no firmware entry is. That is the half-installed shape this page describes: the module made it in, the payload did not.
• Both the module and firmware are present, and the probe still fails. At that point the image content is not the problem. Read the exact path the driver opens and revisit load ordering rather than rebuilding the same image again.

The command checks both artefacts deliberately: grep -i firmware alone cannot distinguish a missing module from a module whose payload path never matched.

I would not rebuild an image that already contains what it needs. A rebuild that changes nothing also destroys the evidence, and the second boot is cheaper to read than the third rebuild is to explain.

Rebuilding gpu unlock with the right generator

Use the generator that produced the image you are booting, not the one that is installed and idle. On a Debian box that boots through dracut, update-initramfs writes a file nobody reads.

• Where the drop-in goes, by initramfs generator.

• mkinitcpio (Arch, CachyOS)

  Drop-in path

  /etc/mkinitcpio.conf.d/zz-gpu-unlock.conf

  What to watch

  A build with -c or a preset _config ignores the drop-in directory.

• initramfs-tools (Debian, Ubuntu to 25.04)

  Drop-in path

  /usr/share/initramfs-tools/modules.d/gpu-unlock.conf

  What to watch

  Builds the module for every kernel that has headers.

• dracut (Fedora, RHEL, Ubuntu 25.10+)

  Drop-in path

  /usr/lib/dracut/dracut.conf.d/gpu-unlock.conf

  What to watch

  The Debian package does not ship this file, which is issue #54.

The package gap in that last row is worth stating plainly: the Debian package writes the initramfs-tools path, and Ubuntu 25.10 moved to dracut, so the module never reaches the image by the packaged route.

issue #54 is where that was reported, and it remains the shortest explanation for gpu_unlock firmware load failed -2 on a fresh Ubuntu install that followed the instructions. [issue #54]

Reinstalling with the same path you used the first time is steadier than copying a blob by hand, because the firmware comes out of that build. If the install cannot produce the payload on this machine, the package is the thing to look at, not the file.

Secure Boot and gpu unlock: two different failures

A signed-boot machine can refuse the module outright. The kernel taints when an unsigned module loads, and with enforcement on it does not load at all. When that happens there is no probe to fail, so there is no -2 to read either.

The correction matters because it decides which fix goes first. Secure Boot rejection happens before the module runs; -2 happens after it runs and the driver fails to find its payload. Two failures, two different layers, and stacking them produces a machine where neither fix lands.

issue #173 is the working path: Fedora 43, Secure Boot on, module signed through MOK. [issue #173]

Telling gpu unlock -2 from the other codes

Four codes account for most of the failure reports, and they are routinely mixed up. Reading the log line is faster than reading the number.

• What each code means and which layer failed.

• -16

  Log line to look for

  RmInitAdapter failed / EBUSY

  Layer that failed

  The device was already bound. Load ordering.

• -2

  Log line to look for

  Failed to load firmware / ENOENT

  Layer that failed

  The payload was not in the image.

• -110

  Log line to look for

  GPU is lost / ETIMEDOUT

  Layer that failed

  The card stopped answering, usually on a warm boot.

• -19

  Log line to look for

  ENODEV

  Layer that failed

  Turing, or a payload that does not match the device.

A rebuilt image still has to meet a cold boot, which is why the -110 page is the next stop after this one. Rebuild first, then power-cycle: a card that timed out during the previous attempt will not be rescued by the new image alone.

Your next gpu unlock firmware step

If the payload was missing, rebuild with your generator and verify before the next reboot. If the image already carried it, read the probe line again and treat the code you get as new information rather than as the same failure twice.

The install order for each generator is on the gpu unlock install page, and whether the card is in the unlock table at all is on the gpu unlock compatibility table. If the log now shows a different code, the troubleshooting index has one page per failure, and the four are not interchangeable.