Magisk Module Not Working In KernelSU: A Comprehensive Troubleshooting Guide

Understanding The Core Conflict Between Magisk Modules And KernelSU

We understand the frustration when a trusted Magisk module fails to function correctly after switching to KernelSU or installing a new kernel. The issue of a Magisk module not working in KernelSU is a common problem rooted in the fundamental architectural differences between these two powerful rooting solutions. While both provide root access, they operate on entirely different principles. Magisk primarily functions as a systemless interface, utilizing a modified boot image to inject its capabilities. It intercepts system calls and provides root through a userspace daemon. KernelSU, on the other hand, is a kernel-based root solution. It modifies the kernel itself, directly patching the kernel source code to manage root access at the kernel level through an internal manager app.

This distinction is critical. Magisk modules are designed with the assumption that the Magisk daemon (magiskd) is running and the Magisk environment is present. These modules rely on Magisk’s specific mount mechanisms, service scripts, and the “magic mount” system to overlay their files onto the system without physically altering the system partition. When a user has KernelSU but not Magisk, or has both but the module is installed in a way that expects the Magisk environment, the module’s installation script will fail. It will look for Magisk-specific variables and directories, such as $MODDIR, $MODPATH, and the magisk binary, which simply do not exist in a pure KernelSU environment. Consequently, the module’s files are never mounted, its scripts are never executed, and the desired functionality is never activated.

Therefore, the first step in our troubleshooting process is to establish a clear diagnosis of the environment. Are you attempting to use a module that requires the full Magisk framework on a device that is only rooted with KernelSU? Are you using a module that is specifically designed for KernelSU? Or are you in a hybrid environment where both systems are installed, potentially causing conflicts? We will explore each of these scenarios and provide a detailed, step-by-step methodology to resolve the issue and ensure your modules function as intended.

Differentiating The Root Frameworks: Magisk vs. KernelSU

To effectively solve the problem, we must first appreciate the technical divergence between the two systems. This understanding informs every subsequent step, from module selection to manual porting.

The Magisk Ecosystem

The traditional Magisk ecosystem is built around a userspace daemon and a suite of scripts that run during the boot process. When a Magisk module is installed, its update-binary is executed within the Magisk environment. This binary unpacks the module’s payload, places files in a designated temporary directory, and then uses magiskpolicy to apply SELinux rules. The most crucial step is the “magic mount.” Magisk creates a series of bind mounts that overlay the module’s files onto the real system partition, making them appear to be part of the system without actually touching it. This process is entirely dependent on the presence of the Magisk infrastructure, including the magisk binary, the magiskpolicy binary, and the running magiskd daemon.

The KernelSU Architecture

KernelSU takes a more direct approach. By integrating root functionality directly into the kernel, it gains the highest level of privilege from the moment the kernel loads. Its manager app communicates with the kernel via a custom driver. KernelSU manages modules and root permissions through its own manager app. While it can execute scripts and mount partitions, its methodology is different. It does not use the Magisk “magic mount” system. Instead, it relies on its own module system, which is fundamentally designed to work with its kernel-level base. The scripts it runs and the environment variables it provides are specific to KernelSU. A standard Magisk module’s service.sh will not be automatically picked up and executed by KernelSU.

Preliminary Diagnosis: Is It A KernelSU Compatibility Issue Or A Module Conflict?

Before diving into complex solutions, we must perform a systematic diagnosis. We recommend our users follow this checklist to pinpoint the exact nature of the problem.

1. Verify Root Method: The most common issue is attempting to use a module designed exclusively for Magisk on a device rooted only with KernelSU. Use a root checker application or a terminal command (su -c whoami) to confirm that KernelSU is the active root manager.
2. Check The Module’s Origin: Where did you download the module? If it is from the standard Magisk Module Repo, it is almost certainly designed for the Magisk environment. Look for any documentation or developer notes that explicitly mention KernelSU compatibility. Modules developed by the community specifically for KernelSU are becoming more common, but they are not the norm.
3. Examine Logs: Logs are your best friend. A magisk_log file might still be generated if Magisk was previously installed, but for a pure KernelSU setup, you must check KernelSU’s own log. A verbose boot log can often reveal why a script failed. Look for errors like “command not found” (referring to Magisk binaries) or “permission denied” (due to incorrect SELinux context or mount points).
4. Identify Conflicting Modules: If you are running both Magisk and KernelSU (a less common and potentially unstable setup), a module might be failing due to a conflict between the two root managers fighting for control over the same system partitions. We strongly advise against using both simultaneously unless you are an advanced user experimenting with a specific setup.

The Primary Solution: How To Make Magisk Modules Work With KernelSU

For users who wish to run a standard Magisk module on a KernelSU-powered device, a direct installation will not suffice. We must perform a manual “porting” process. This involves extracting the necessary files and scripts from the module and executing them using KernelSU’s environment. This process requires caution and precision.

Step 1: Acquiring The Module Files

First, you need the module’s contents. You can get this by renaming the module’s .zip file to .rar or .zip and extracting it. Alternatively, if you have the module installed on a Magisk device, you can navigate to /data/adb/modules/<module_name> and copy its contents. You are looking for the core components:

• The module.prop file (for identification).
• The system folder (containing the files to be overlaid).
• Any .sh scripts, such as service.sh, post-fs-data.sh, or a custom install.sh.
• Any binaries located in a bin folder.

Step 2: Understanding KernelSU’s Directory Structure

KernelSU, like Magisk, operates from /data/adb. However, it does not have the same module folder structure. For manually installing a module, we will create our own structure within KernelSU’s service script directory. The primary location for custom scripts that run at boot is /data/adb/ksu/service.d. Scripts placed here will be executed with root privileges during the boot process, similar to Magisk’s service.sh.

Step 3: Manual Installation And Scripting

This is the most technical part of the process. We will move the module’s files to their appropriate locations and create a script to handle the mounts.

1. Copy System Files: Navigate to /data/adb/ and create a directory for your manual module, for example, /data/adb/manual_modules/<module_name>. Copy the system folder from the extracted module into this new directory. The structure inside should mirror the root filesystem, e.g., /data/adb/manual_modules/<module_name>/system/etc/audio_effects.conf.

2. Create The Mounting Script: The magic of Magisk’s systemless mount needs to be replicated manually. We will do this by creating a script in /data/adb/ksu/service.d/. Name it descriptively, like 99_<module_name>_mount.sh. The script will need to perform bind mounts for each file/folder the module provides. A typical mount command looks like this: mount -o bind /data/adb/manual_modules/<module_name>/system/path/to/file /system/path/to/file You must create a mount command for every single file and folder the module is supposed to overlay. For a complex module, this can involve many lines. The script must be executable (chmod +x). The script should also include checks to ensure the target mount point is not already mounted by another module.

3. Handle SELinux Contexts: A common point of failure is incorrect SELinux labeling. KernelSU’s manager may automatically relabel some files, but it is not guaranteed. You may need to add restorecon commands to your script. For example: restorecon -R /data/adb/manual_modules/<module_name>/system/ restorecon /system/path/to/file This ensures the kernel’s security policy recognizes the files correctly.

4. Execute Module Scripts: If the module requires a service.sh to run background processes or set permissions, you need to execute this script manually. You can place the module’s original service.sh in your manual module directory and call it from your mount script, or create a new entry in /data/adb/ksu/service.d/ to run it. The original script may contain Magisk-specific variables ($MODDIR), which will need to be edited and replaced with the paths you are using in your manual installation.

Step 4: Reboot And Verify

After you have meticulously copied the files and created the necessary scripts, a reboot is required. After the device restarts, verify if the module is working. If not, you must immediately check the logs again. The log output from your custom scripts in /data/adb/ksu/service.d/ can be redirected to a log file for easier debugging. For example, you can start your script with exec > /data/adb/ksu/manual_module_log.txt 2>&1 to capture all output.

Advanced Troubleshooting: Resolving Persistent Issues

Sometimes, even after a manual port, a module may not work. This could be due to a variety of complex reasons.

Proprietary Kernel And Module Mismatches

Some modules are designed to work with specific kernel features or drivers. If your kernel lacks these features, the module will fail. For instance, a module that modifies a specific CPU governor will only work if that governor is present and supported by your kernel. You must verify that your kernel is compatible with the module’s function.

Zygisk And LSPosed Framework Incompatibility

Many popular Magisk modules are designed to work in conjunction with Zygisk and the LSPosed framework. These modules do not perform direct file modifications but instead use the LSPosed framework to inject code into specific system apps. If you are using KernelSU, you must install LSPosed specifically for KernelSU. The standard Magisk version of LSPosed will not function. You must then ensure that the target module is configured to work with the KernelSU version of LSPosed. This often involves using the “System Framework” module template which LSPosed provides.

Magisk Delta And KernelSU Coexistence

Some users run Magisk Delta alongside KernelSU. Magisk Delta has a “Systemless Hosts” module and other features that can conflict with KernelSU’s own functions. If you are in this situation, the most likely culprit is a conflict in the /system mount points. We recommend a clean setup. If your goal is simply root, stick to one. If you need specific features from both, you must isolate them carefully. For instance, you could use KernelSU for root and Magisk Delta only for its specific Zygisk/LSPosed environment, but this is an unsupported, experimental configuration.

Checking For Module Updates And Alternatives

The open-source community is dynamic. A module that was broken yesterday might have been fixed today. Always check the source repository, such as GitHub or XDA, for the module. The developer may have released a KernelSU-compatible version or a patch. If the module is abandoned, search for an alternative. The functionality you need might be available in a different module that was built with KernelSU in mind. Our repository at Magisk Module Repository aims to curate modules, but the landscape is constantly changing, and direct developer sources are often the most up-to-date.

Best Practices For A Stable KernelSU Environment

To minimize issues with modules and ensure a stable system, we advocate for the following best practices.

Understand Before You Install

Never install a module without understanding what it does. Read the module’s description and source code if possible. A poorly written module can cause bootloops or system instability. When porting a Magisk module to KernelSU, this step is even more critical, as you are manually implementing its logic.

Maintain A Clean Environment

Avoid mixing rooting solutions unless absolutely necessary. A device with both Magisk and KernelSU is a recipe for conflicts. Choose one primary root manager and stick with it. If you must use a Magisk-exclusive module, consider porting it manually rather than installing the full Magisk framework.

Backup, Backup, Backup

Before making any changes to your system, always have a full backup. This includes a backup of your boot image and critical data. If you are manually mounting files, a mistake can lead to an infinite boot loop. A solid backup is your only safety net.

Conclusion: Mastering The Module Ecosystem

The issue of a Magisk module not working in KernelSU is not a dead end. It is a technical challenge that can be overcome with a proper understanding of the underlying systems and a methodical approach. The key is recognizing that a Magisk module is an application designed for a specific environment. By manually extracting its components and using KernelSU’s own execution methods, we can bridge the gap between the two ecosystems. While this process is more complex than a simple one-click installation, it provides a powerful way to unlock the vast library of Magisk modules within the robust, kernel-level root environment of KernelSU. We encourage users to experiment cautiously, rely on logs for guidance, and contribute their findings back to the community to help others navigate this complex but rewarding technical landscape. For a curated list of modules and further resources, we invite you to explore our collection at Magisk Modules.