Recovering from a bootloop¶

If your device stops booting normally after you flash the Echidna Magisk/Zygisk module, this page walks through recovery options from the least invasive to the most invasive. Try the gentlest one that your device supports and that actually brings the phone back, then stop.

This is the situation the setup wizard made you acknowledge

The first-run wizard requires you to tick "I understand how to recover if a root module bootloops my device" before you can proceed — it is the one step you cannot skip. This page is that recovery knowledge. If you flashed anyway without a plan, read it now, and see Limitations for why the failsafes are guardrails, not guarantees.

⚠️ These are guardrails, not guarantees

Echidna is experimental software for rooted-device power users. The failsafe markers and boot watchdog below are intended to help a prepared user boot again, but they cannot promise recovery on every device. Whether any of this works depends on things Echidna does not control — an unlocked bootloader, whether recovery can decrypt /data, whether adb is available, and your exact device and ROM. If you did not already know how to disable a Magisk/Zygisk module out-of-band before you installed Echidna, you are now in the situation the install docs warned about. See Limitations → Install-risk failsafes are guardrails, not guarantees.

Honest status — recovery is not a promise the effects work

Echidna is experimental and not fully functional. Recovering from a bootloop only gets your phone booting again; it does not mean the voice changer will work on your device afterwards. Do not re-enable the module expecting it to work — re-enable it only if you understand the risk of another bootloop (see step 5).

Before you start¶

Unlocked bootloader. The last-resort fastboot flash steps require an unlocked bootloader. fastboot flash is rejected on a locked bootloader, and unlocking wipes user data on most devices — you cannot unlock after a bootloop to save existing data.
Know your exact device + ROM. Flashing the wrong image or partition can turn a soft bootloop into a hard brick. The image must match your exact device model and ROM/build, and must target the partition Magisk originally patched.
/data may be encrypted. A recovery (TWRP/OrangeFox/LineageOS Recovery) often cannot decrypt or even mount /data. That is why some disable markers live on /cache and /metadata instead — see step 2.
Back up first, always. Make a backup before you flash anything in recovery/fastboot. Recovery steps can and do lose data.
A/B (slot) devices flash to a specific slot — note the A/B guidance in step 4.

Recovery ladder¶

1. Use Magisk's own module recovery controls (gentlest)¶

Use the first option you can reach:

Magisk app. If you can reach the launcher at all, open Magisk → Modules, toggle Echidna off, and reboot.
Magisk Safe Mode. This is separate from Android's Safe Mode. Magisk detects the device's safe-mode key early in boot and creates module disable files. On many devices, press Volume Down several seconds before the boot animation and release it when the animation appears. Timing and keys are device-specific; follow Magisk's bootloop FAQ.
Magisk's adb recovery command. If adb reaches the Magisk daemon, run:

sh adb shell magisk --remove-modules

This removes all Magisk modules and automatically reboots. It is broader than disabling only Echidna, but it is Magisk's documented recovery command.

If none of these are reachable, move to step 2.

2. Create an Echidna disable marker¶

Echidna's boot scripts check for a set of disable markers early in boot. If any one of them is present, the module fails closed for that boot: it removes its staged native library, tears down its shared runtime regions, and touches Magisk's own module disable file so the module stays off. These markers are honored by both post-fs-data.sh and service.sh (manual_disable_marker() in android/control-service/magisk/).

Create the first marker you can actually reach — from adb (adb shell, adb root) if it is available, or from a recovery shell. Pick a marker on a partition your recovery can write to:

Marker path	When to use it
`/data/adb/modules/echidna/disable`	Magisk's standard per-module disable file. Works when `/data` is mounted (and decrypted). Disables just Echidna.
`/data/adb/modules/echidna/remove`	Tells Magisk to uninstall the Echidna module on the next boot. Also honored as a disable marker.
`/data/adb/echidna/disable`	Echidna's own runtime disable marker; keeps Echidna inactive even if the module files remain. Needs `/data`.
`/data/adb/echidna/safe-mode`	Echidna's project safe-mode marker; boots with Echidna disabled so the companion app can report why. Needs `/data`.
`/cache/echidna-disable`	Early marker for when `/data` is encrypted, unavailable, or unsafe to touch from recovery.
`/metadata/echidna-disable`	Same purpose as the `/cache` marker, for devices that expose `/metadata` instead.

For example, from a recovery shell or adb shell where /data is mounted:

```sh

Disable just the Echidna module for the next boot¶

touch /data/adb/modules/echidna/disable

...or, if /data will not mount/decrypt, use an early marker:¶

touch /cache/echidna-disable

or¶

touch /metadata/echidna-disable ```

Then reboot. On the next boot Echidna sees the marker and disables itself.

The automatic boot watchdog may recover it for you

Echidna also arms a boot watchdog in post-fs-data.sh. Each boot that never reaches the late-start service (service.sh) counts as an unfinished boot; after the limit is reached (ECHIDNA_BOOT_FAIL_LIMIT, default 2, minimum 2) the module self-disables — exactly the fail-closed path above. So a bootloop caused only by Echidna will often break on its own after a couple of failed boots. The watchdog state and the reason it tripped are written under /data/adb/echidna/failsafe/ (e.g. reason.txt). Treat the watchdog as a last-resort guard, not your only plan — it cannot help if another module breaks earlier in boot, if /data is unavailable, or if the failure never returns control to the module scripts.

If markers cannot be written (recovery cannot mount/decrypt any writable partition) or do not resolve the loop, move to step 3.

3. Older releases: remove the module and its pre-init policy¶

Reported by Obada8 (OnePlus / OxygenOS 16, Android 16) in issue #14 after two days of searching. Try this before flashing a stock boot.img: it keeps Magisk and root intact, and it recovers the case where deleting the module alone is not enough.

This applies only to packages containing root-level sepolicy.rule

Older Echidna releases shipped Magisk's special root-level sepolicy.rule. Magisk may store that policy outside the module directory and apply it before post-fs-data.sh, so deleting the module alone may not stop an early failure. Current packages keep the reviewed rules under a non-special filename and apply them live only after Echidna's disable-marker checks.

Boot a custom recovery, then from a PC with adb:

```sh

1. Remove any Echidna module, in both the live and staged module directories¶

adb shell "for d in /data/adb/modules/ /data/adb/modules_update/; do \ if [ -f \$d/module.prop ] && grep -qi echidna \$d/module.prop; then \ echo REMOVING:\$d; rm -rf \$d; fi; done"

2. Drop Magisk's stored pre-init sepolicy so the module's rules stop being applied¶

adb shell "rm -rf /metadata/watchdog/magisk"

3. Flush to disk, then reboot¶

adb shell "sync" adb reboot ```

What step 2 actually removes

It removes Magisk's cached pre-init policy, not Magisk itself and not your other modules' files. Magisk regenerates the policy on the next boot from the sepolicy.rule of whichever modules are still installed — which is exactly why step 1 must come first. If your device stores the pre-init policy elsewhere, the same reasoning applies to that path instead.

If the device still will not boot after this, move to step 4.

4. Restore the exact stock image Magisk patched (removes Magisk)¶

This is the recovery-of-last-resort used successfully by the reporter in issue #17 (a Poco X3 NFC on LineageOS 22.2). Depending on the device, Magisk patches boot, init_boot, or recovery. Restoring the matching stock image removes Magisk and therefore Echidna with it.

Requires the exact image, partition, slot, device, and build

This works only with an unlocked bootloader, and you must flash the stock image matching your exact device and exact ROM/build to the partition Magisk actually patched. Guessing can hard-brick the device.

Reboot into fastboot / bootloader mode. From a powered-off device the key combo is usually Volume Down + Power (device-specific); or from adb:

sh adb reboot bootloader

Identify what Magisk patched, then obtain that exact stock image. Consult the original rooting instructions and Magisk installation record for the device. The target may be boot, init_boot, or recovery. Good sources, in rough order of preference:
Magisk's own backup, if it exists: Magisk backs the original image up to /data/adb/magisk/stock_boot.img.gz at patch time. If you can still read /data, restoring that (or using Magisk app → Uninstall → Restore Images before it broke) gives you the exact pre-root image.
The ROM you are running — e.g. the exact LineageOS or OEM build for your device — which contains the matching partition image.
The factory image / OTA for your device build, from which boot.img or init_boot.img can be extracted.
Flash only the partition Magisk originally patched:

sh # Use exactly one command, matching the original Magisk installation: fastboot flash boot boot.img # or fastboot flash init_boot init_boot.img # or, only on devices where Magisk was installed into recovery fastboot flash recovery recovery.img fastboot reboot

The device should boot again.

A/B (slot) devices¶

Many modern devices are A/B and use slotted partitions. Check the active slot:

sh fastboot getvar current-slot

Follow the device or ROM's exact restore instructions for that slot. Do not blindly flash both slots: the inactive slot may contain a different build.

5. Reinstall Magisk cleanly¶

Restoring the stock boot, init_boot, or recovery image in step 4 removed Magisk, so root is gone. If you want root back, reinstall Magisk properly for your device by following Magisk's current installation documentation.

Remove or disable the Echidna module BEFORE you re-root

Re-enabling root with the Echidna module still present can cause another bootloop. Before you reboot into a freshly re-rooted system, make sure Echidna will not load again — do one of:

Delete the module directory /data/adb/modules/echidna (or drop a .../echidna/remove marker so Magisk uninstalls it), or
Create a disable marker from step 2 (e.g. /data/adb/echidna/disable), or
Restore images via Magisk's own backup rather than re-patching over a state that still contains the module.

Only after Echidna is removed/disabled should you re-root and reboot.

After recovery¶

Getting back to a booting phone does not mean Echidna will work — it is experimental and may not function on your device even after a clean reinstall. If you choose to try Echidna again, re-read Build & Install and the Limitations first, and only re-enable the module if you are prepared to run this recovery again.

Credits¶

The stock-image recovery method documented in step 4 was reported by MrLeyYT (Poco X3 NFC / LineageOS 22.2) in GitHub issue #17. Thanks for writing up the recovery.

The recovery-shell module removal in step 3 — and the key insight that Magisk's stored pre-init sepolicy must be cleared too, because deleting the module directory alone leaves the boot-breaking rules in place — was reported by Obada8 (OnePlus / OxygenOS 16, Android 16) in GitHub issue #14, after spending two days finding it. Thanks for going back and writing it up for the next person.