ReaderTweaks

Kindle Paperwhite · Troubleshooting

KOReader won't launch on the Kindle Paperwhite

KOReader was installed on a jailbroken Paperwhite but will not start, the KUAL entry is missing, or it stopped working after a firmware update.

Software
KOReader 2024.11
Difficulty
Advanced
Time
30 to 60 minutes
Last tested
August 2026
Last updated
August 2026

Symptoms

  • The KUAL "book" is missing from the Library.
  • KUAL opens but has no KOReader entry, or the entry does nothing.
  • KOReader worked before and disappeared after the Kindle updated its firmware.
  • Choosing KOReader shows a black screen, then returns to the Kindle.

Before you start

  • Check the current firmware version — Settings, then Device Options, then Device Info.
  • Have the computer, cable and the KOReader, KUAL and hotfix packages you used before.
  • Know that this only concerns KOReader and the jailbreak; your Amazon books are untouched.

Which fix do you need?

When did it stop working?

Most common cause

By far the most common cause is a firmware update. A Kindle that updated itself over Wi-Fi removes the jailbreak, and with it KUAL and KOReader, even though the KOReader files may still be on the drive. The next most common cause is files that were copied to the wrong folder, so KUAL never picked up the KOReader action.

Fixes

Fix 1 Check the files are where KUAL expects them

KUAL only shows a KOReader action if the KOReader package and its KUAL "extension" are in the exact folders the readme specifies. A folder one level too deep is invisible to it.

  1. Connect the Kindle and open its drive. Confirm there is an "extensions" folder at the root, with a "koreader" (or similarly named) folder inside it that contains a "menu.json" or "config.xml".
  2. Confirm the KOReader program itself is where its installer put it — usually a "koreader" folder at the root, or unpacked by the installer from a package in "documents".
  3. If anything is nested inside an extra folder such as "koreader-kindle-2024.11", move its contents up to the correct level.
  4. Eject safely, unplug, and open KUAL again to see if the action appears.

Fix 2 Redo the jailbreak if a firmware update removed it

A firmware update disables the jailbreak. KUAL and KOReader vanish because the system will no longer run unsigned software, even though the files remain. There is no way around re-doing the jailbreak for the new firmware.

  1. Check the firmware version. If it is higher than it was, the update is the cause.
  2. On the MobileRead forums, find the jailbreak method for this exact firmware version. If one exists, follow it, then reinstall KUAL, the update hotfix and KOReader as in the install guide.
  3. Install the update hotfix again straight away, and keep the Kindle in airplane mode except for deliberate syncs, so this does not recur.
  4. If no jailbreak exists yet for this firmware, KOReader cannot run until one is released. Use the stock reader in the meantime.

Fix 3 Reinstall the KOReader package

If KUAL works and the jailbreak is intact but KOReader still will not start, the KOReader files themselves are likely incomplete or damaged from an interrupted copy.

  1. Download the current "koreader-kindle" package again, in full.
  2. Connect the Kindle, copy the package to the location its readme specifies, replacing the old files.
  3. Eject, unplug, open KUAL and run "Install or update KOReader" (the MRPI action).
  4. Start KOReader from KUAL. If it now shows an error naming a specific ".lua" file, delete the "koreader" folder entirely and reinstall from scratch.

Undo / recovery

To remove KOReader and the jailbreak and return the Paperwhite to stock: install the "uninstall" actions from KUAL if present, then delete the "koreader" and "extensions" folders and the KUAL document from the drive. A firmware update or a full device Reset from Device Options also removes everything and restores the stock software; a Reset erases downloaded books but not Amazon purchases.

If KOReader stopped working, check the firmware version first — an update is the cause far more often than anything else, and Fix 2 is then the only real option. For a fresh install that never ran, Fix 1 covers the usual folder mistakes.