Skip to content

Troubleshooting

Jump to bottom
Luke Horwell edited this page Jun 18, 2024 · 25 revisions

Troubleshooting Guide

The most common issues are listed below. Please check here before opening an issue!

Check device support

To list USB PIDs for your Razer hardware, run this in a Terminal:

lsusb | grep 1532

👉🏼 Check your device ID matches a device on this stable release list.

❌ If it's not listed, does your device appear in this list instead? If so, that would mean support was recently added, so you'll need to install a development build until the next release:

(Be sure to reboot after installing different versions of the driver)

❌ If your device USB PID does not appear on these lists, it is not yet supported. Check for open issues & pull requests and subscribe to them for updates, or try implementing support yourself. For new devices with a different USB PID, please create a new issue.

Is OpenRazer up-to-date?

Some Linux distributions package OpenRazer into their official repositories. Sometimes, this version is for an older version which did not have support for your device. Try installing using the instructions from our website, which is packaged for the latest version.

Kernel Modules: Are they built properly?

You can check if the kernel modules build properly with the following command (replace $version with the version of OpenRazer you have installed, e.g. 3.2.0)

sudo dkms install openrazer-driver/$version

✅ If the output is similar to:

Module openrazer-driver/2.5.0 already installed on kernel 5.2.0-arch2-1-ARCH/x86_64

Success! The kernel modules are built properly.

⚠️ If you have multiple kernels installed, make sure the driver is built for the correct kernel version. Confirm this with:

uname -r
sudo dkms status

⛔ If the output is:

Error! Could not find module source directory.
Directory: /usr/src/openrazer-driver-3.3.0 does not exist.

The driver is missing. Install the openrazer-driver-dkms package for your distribution. openrazer-meta normally installs this dependency.

In some cases, after installing this package, you may need to run the dkms install command above again.

⛔ If the output is similar to:

Creating symlink /var/lib/dkms/openrazer-driver/2.5.0/source ->
                 /usr/src/openrazer-driver-2.5.0

DKMS: add completed.
Error! echo
Your kernel headers for kernel 5.2.0-arch2-1-ARCH cannot be found at
/usr/lib/modules/5.2.0-arch2-1-ARCH/build or /usr/lib/modules/5.2.0-arch2-1-ARCH/source.

The kernel headers for your current kernel are not installed.

  • On Arch Linux (+ derivatives), the kernel headers aren't a hard dependency of the dkms package because you can install different kernel flavors that have separate header packages. On Arch Linux you will probably have to install linux-headers. Manjaro packages their kernel by version so for example, for the 4.19 kernel, install the package linux419-headers.
  • On Fedora, you are likely missing the kernel-devel package.
  • On Ubuntu, this is usually linux-headers-generic or linux-headers-generic-hwe-20.04 (HWE).

Kernel Modules: Do they load properly?

You can try loading the kernel module built by DKMS with

sudo modprobe razerkbd

(Possible modules: razerkbd, razermouse, razeraccessory, razerkraken)

✅ No output indicates success.

⛔ If this fails with:

modprobe: FATAL: Module razerkbd not found in directory

The driver is not installed for this kernel. Please go back to the last section to install them.

⛔ If this fails with:

modprobe: ERROR: could not insert 'razerkbd': Invalid argument

It's likely the driver was not built properly or is outdated. For example, the system was updated to a newer kernel, but the driver is still built with older kernel headers. Reinstalling the driver via DKMS should do the trick:

sudo dkms remove openrazer-driver/3.8.0 --all
sudo dkms install openrazer-driver/3.8.0

(Replace 3.8.0 with the appropriate OpenRazer version)

⛔ If this fails with:

modprobe: ERROR: could not insert 'razerkbd': Required key not available

or

modprobe: ERROR: could not insert 'razerkbd': Operation not permitted

or

modprobe: ERROR: could not insert 'razerkbd': Key was rejected by service

This is probably because Secure Boot is enabled in your BIOS/UEFI settings.

Since OpenRazer is an out-of-tree driver in the form of source code, the module is built locally for your kernel during installation (and repeats again when the kernel is upgraded). For most distros, this done by DKMS. Unfortunately, nothing signs that binary so the kernel refuses to load OpenRazer while secure boot is on.

The easiest solution is to disable secure boot. This allows your system to load unsigned drivers.

The complicated solution is to sign the module yourself. OpenRazer can't do this as we are not distributing a kernel or binary. Debian has some good documentation on Secure Boot, but please use your favourite search engine on how to sign them for your distro.

Other security solutions like kernel lockdown could also prohibit you from loading an (unsigned) kernel module. If you have a feature like this enabled, make sure those are also configured appropriately.

Daemon: Has your user been added to the plugdev group?

The OpenRazer daemon will refuse to start, if the current user isn't in the plugdev group which is needed to give your user permissions to access to sysfs files provided by the kernel modules. You will either see this in ~/.local/share/openrazer/logs/razer.log or when you start the daemon with openrazer-daemon -Fv in the terminal.

If you get the message Unable to lock on the pidfile., it means that the daemon is already running.

To fix this error, please run this command and reboot:

sudo gpasswd -a $USER plugdev

Where to find logs

  • List currently loaded modules:

    lsmod | grep razer

  • Kernel module log:

    dmesg | grep razer

  • razer_mount log:

    sudo journalctl -b | grep -i razer_mount

  • Daemon log:

    cat ~/.local/share/openrazer/logs/razer.log

  • List sysfs permissions for driver device files:

    ls -al /sys/bus/hid/drivers/razer*/*1532*/

Try searching open & closed issues to see if this is a bug, an external problem affecting your system or a hardware-specific issue.

Clone this wiki locally