Check for unresolved symbols for kernel modules after update

Unresolved symbols in kernel modules after an update typically indicate a mismatch between the running kernel version and the installed module packages, or missing dependency files. The primary diagnostic command is modprobe, which reports specific symbol errors when it fails to load a module. Resolving this requires verifying that the modules.dep file is up-to-date and that the kernel headers match the currently running kernel version.

Identifying Unresolved Symbols

When you attempt to load a kernel module using modprobe, the system checks for all required symbols defined in the kernel image. If a symbol is missing, the command will fail with an error message similar to "Unknown symbol in module" or "Symbol not found." This is the most direct way to identify which specific symbols are unresolved. You can also use lsmod to list currently loaded modules. While this does not directly show unresolved symbols for unloaded modules, it helps confirm whether the kernel itself is functioning correctly. If a module fails to load due to unresolved symbols, it will simply not appear in the output of lsmod. To get detailed information about why a module failed to load, check the system logs. The dmesg command displays kernel ring buffer messages. Look for lines containing "module" and "symbol" or "error." For example:

dmesg | grep -i "unresolved symbol"

This will filter the log output to show only relevant entries. The output will include the name of the module, the missing symbol, and often the source file where the symbol is expected. This information is crucial for determining whether the issue lies with the module itself or the kernel configuration.

Verifying Kernel and Module Consistency

The most common cause of unresolved symbols is a version mismatch. After a kernel update, the running kernel may have changed, but the module packages (such as those in /lib/modules/$(uname -r)/) may still belong to the old kernel version. You must ensure that the directory structure under /lib/modules/ matches the output of uname -r. If you recently updated your kernel, verify that the new kernel headers are installed. Many proprietary or out-of-tree modules require header files to compile against the current kernel. On Debian-based systems, you can install these with:

apt-get install linux-headers-$(uname -r)

On Yocto Project builds, the process is more integrated into the build system. Ensure that the kernel-devicetree and kernel-image packages are correctly generated and deployed. Mismatches here often result in subtle symbol issues because the module was compiled against a different internal API than what is present in the running kernel. If you suspect a package management issue, such as broken dependencies, you might encounter errors like those described in Fixing E: Sub-process /usr/bin/dpkg returned an error code (1) on Kali Linux. While this specific guide addresses dpkg errors, the underlying principle of ensuring package integrity applies broadly to any Linux distribution. A corrupted package installation can lead to missing symbol files or incomplete module directories.

Updating Module Dependencies

Even if the correct kernel version is installed, the dependency map might be stale. The modules.dep file maps each module to its dependencies. If this file is outdated, modprobe may not find the necessary symbols even if they exist in other modules. Regenerate the dependency map by running depmod. This command scans the /lib/modules/ directory and updates modules.dep, modules.alias, and modules.symbols.

depmod -a

The -a flag ensures that all available modules are processed. Run this command as root. After executing depmod, try loading the problematic module again. If the symbol is now resolved, the issue was simply a stale dependency database. In some cases, particularly with custom or manually compiled modules, you may need to specify the path explicitly:

depmod -b /path/to/modules/dir -a

This is useful if your modules are installed in a non-standard location. Always verify that the path contains the correct kernel version subdirectory.

Debugging Custom Modules

For modules built from source, unresolved symbols often stem from incorrect build configurations. Ensure that the module was compiled against the same kernel source tree that produced the running kernel. Using make modules_prepare in the kernel source directory prepares the environment for external module builds. Check the Makefile of your module. It should reference the correct kernel source directory via the KDIR variable. If you are using the Yocto Project, remember that cross-compilation environments can sometimes lead to path mismatches if the sysroot is not correctly configured. See How to Rebuild and Install RISC-V Kernel Cross Compile for insights into managing complex build environments, although the specific architecture differs, the principles of ensuring build consistency remain valid. Avoid blindly removing files like modules.builtin* without understanding their role. These files contain lists of modules that are built into the kernel image. Removing them incorrectly can break the dependency resolution process entirely. Instead, focus on regenerating the dependency map and verifying the kernel version match.

Frequently Asked Questions

Why does modprobe fail with "Unknown symbol"?

This error occurs when the module references a function or variable that is not exported by the running kernel. It usually indicates a version mismatch between the module and the kernel, or that the kernel was compiled without the necessary configuration option.

How do I check if my kernel headers match my running kernel?

Compare the output of uname -r with the directory names in /lib/modules/. They must match exactly. Additionally, verify that the linux-headers package is installed for that specific version.

Can unresolved symbols cause system instability?

Generally, no. Unresolved symbols prevent the module from loading, which means the functionality provided by that module is unavailable. However, if critical hardware drivers fail to load, it may affect device connectivity or performance.

What is the difference between modules.dep and modules.symbols?

modules.dep lists the dependencies between modules, indicating which modules must be loaded before others. modules.symbols maps symbol names to the modules that provide them, allowing modprobe to resolve symbol requests across different modules.

Should I reinstall the kernel after updating?

Not necessarily. If the kernel update was successful and the modules.dep file has been regenerated with depmod -a, reinstallation is rarely needed. Only reinstall if the kernel image itself is corrupted or if boot failures occur.