Skip to content

Troubleshooting

Jump to bottom
LukeZGD edited this page Jul 1, 2024 · 184 revisions

Common issues

  • If something in the process does not work for you: try unplugging/replugging the device, switching between different USB ports/cables, also try USB 2.0 or 3.0 ports
  • IPSW file integrity will be verified before restoring and/or creating custom IPSW (if custom IPSW is already created, this will be skipped) This is done to make sure that the IPSW is not corrupt or incomplete.
  • For users having issues with missing libraries/tools: re-install dependencies by deleting the firstrun file in resources, then run the script again.
  • If your device is not being detected in normal mode, make sure to also trust the computer by selecting "Trust" at the pop-up.
    • macOS/Windows: Double-check if the device is being detected by iTunes/Finder.
  • 32-bit devices: If SSH fails for you, try these steps to make sure that SSH is successful
  • Exit DFU Mode: Hold the TOP and HOME buttons of your device for about 15 seconds.
  • Exit Recovery Mode: Run the script while the device is in recovery mode, select Downgrade Device, and select the option to exit recovery.
  • When opening an issue, send the FULL log. If you only send a partial log or not send a log at all, your issue will be dismissed and closed.
  • Using manually saved SHSH blobs
  • Clearing NVRAM

Script arguments

  • EntryDevice - If the script is reading the ECID of your device incorrectly, you can enter it manually. To do this, run the script with --entry-device as an argument.
  • NoColor - If the text displayed by the script is unreadable because of the color, you can disable it. To do this, run the script with --no-color as an argument.
  • NoDevice - To perform operations without an iOS device connected, run the script with --no-device as an argument.
    • In NoDevice mode, your only options are to Save OTA Blobs, and Create Custom IPSW for 32-bit devices.
  • Example of usage with argument: ./restore.sh --no-color --entry-device
    • The script accepts multiple arguments
  • There are 2 optional arguments --disable-sudoloop and --disable-usbmuxd for Linux. (I don't recommend enabling any of these since default behavior should work fine in most cases, maybe only --disable-usbmuxd will be useful in case)
    • By default, Legacy iOS Kit stops the usbmuxd service and starts up sudo usbmuxd -pz. The --disable-usbmuxd argument disables this
    • By default, Legacy iOS Kit runs some tools as root like irecovery and idevicerestore among others. The --disable-sudoloop argument disables this
  • Other options (full output of --help):
 *** Legacy iOS Kit ***
  - Script by LukeZGD -

Usage: ./restore.sh [Options]

List of options:
    --debug                   For script debugging (set -x and debug mode)
    --disable-sudoloop        Disable running tools as root for Linux
    --disable-usbmuxd         Disable running usbmuxd as root for Linux
    --entry-device            Enable manual device and ECID entry
    --help                    Display this help message
    --no-color                Disable colors for script output
    --no-device               Enable no device mode
    --no-version-check        Disable script version checking

For 32-bit devices compatible with restores/downgrades (see README):
    --activation-records      Enable dumping/stitching activation records
    --disable-bbupdate        Disable bbupdate and enable dumping/stitching baseband
    --gasgauge-patch          Enable multipatch to get past "gas gauge" error (aka error 29 in iTunes)
    --ipsw-hacktivate         Enable hacktivation for creating IPSW (iPhone 2G/3G/3GS only)
    --ipsw-verbose            Enable verbose boot option (powdersn0w only)
    --jailbreak               Enable jailbreak option
    --memory                  Enable memory option for creating IPSW
    --pwned-recovery          Assume that device is in pwned recovery mode
    --skip-ibss               Assume that pwned iBSS has already been sent to device

    * Default IPSW path: <script location>/name_of_ipswfile.ipsw
    * Default SHSH path: <script location>/saved/shsh/name_of_blobfile.shsh(2)

Notes for iPhone 4 powdersn0w

  • If you want to go back and restore to iOS 7.1.2, you need to disable the exploit
  • This script uses powdersn0w and mostly automates the downgrade process for the iPhone 4
  • This supports iPhone 4 GSM and CDMA (iPhone3,1 and 3,3)
    • Restoring with blobs, restoring to 7.1.2, and entering kDFU mode supports all iPhone 4 models
  • The downgrades have the option to jailbreak
  • Take note that not all downgrades are compatible with all models
    • 8GB models may not work with downgrades below iOS 6
    • Newer models may not work with downgrades below iOS 5
    • If your device is not compatible as mentioned, you will get the error Unable to find AppleNANDFTL
    • You can use sites like Reincubate to check whether your device is compatible or not (Reincubate might be inaccurate, so find better sites like sickw or sndeep)

Notes for iPad 1 and iPod touch 3 powdersn0w

  • If you want to go back and restore to iOS 5.1.1, you need to disable the exploit
  • To fix getting stuck in recovery mode after the restore to 4.3.x, try going to: Other Utilities -> Disable/Enable Exploit -> Enable exploit

macOS

  • macOS users should install bash, curl, and libusb from Homebrew or MacPorts. This is optional, but recommended.
    • For Homebrew: brew install bash curl libusb
    • For MacPorts: sudo port install bash curl libusb
  • If some tools are not working, you may try to git clone the repo: git clone https://github.com/LukeZGD/Legacy-iOS-Kit.git then try again from there
    • You may also try this: cd to where the files are extracted, then run sudo xattr -cr bin/macos
    • If nothing else works, you may have to try disabling Gatekeeper: sudo spctl --master-disable

Linux

  • checkm8 is unfortunately very unreliable on Linux, you may have to try multiple times.
  • You may also try in a live USB
  • You may have to get a machine running macOS to get your device to enter pwnDFU mode, or use iPwnder Lite for iOS
  • For advanced users: Hackintosh and macOS KVM with USB passthrough should also work if set up properly

Windows

  • Windows users should use Legacy iOS Kit on Linux or macOS instead.
  • You can easily create an Ubuntu live USB with tools like Rufus. Make sure to enable Persistent Storage, or use another USB drive to store Legacy iOS Kit and its files.
  • Support for iPhone 4 and A7 devices is limited. More details below.
  • Windows users may encounter errors like Unable to send APTicket or Unable to send iBEC in the restore process.
    • To exit recovery, run the script again and go to Other Utilities -> Exit Recovery Mode.
    • Verify your iTunes version: Open iTunes -> Help -> About iTunes. Legacy iOS Kit can also detect your iTunes version.
    • You should have iTunes version 12.6.5 or older. Downgrade your iTunes version first before attempting any other fixes.
    • To attempt to fix this, follow steps 1 to 5 here.
    • After downgrading iTunes and/or attempting the fix, follow the procedure again. This time, it should get past the previous errors mentioned.
    • If the troubleshooting steps do not work, consider creating a Linux live USB with persistent storage.
    • More troubleshooting steps here
  • If you want to restore your iPhone 4 or A7 device on Windows, you need to first put the device in pwnDFU mode with signature checks disabled. Since entering pwnDFU mode is not supported on Windows, you need to use a Mac/Linux machine or another iOS device to do so. If your device is not in pwnDFU mode, the restore will NOT proceed.

A7 devices

  • Do not use USB-C to lightning cables. Use USB-A to lightning cables only. You may use a USB-A to USB-C adapter if needed.
  • Entering pwnDFU mode can fail a lot on Linux especially for A7 devices.
  • Entering pwnDFU mode will likely fail on devices running AMD CPUs.
  • If the script cannot find your device in pwnREC mode or gets stuck, you may have to start over by force restarting and re-entering recovery/DFU mode
  • Use an Intel or Apple Silicon PC/Mac as entering pwnDFU (checkm8) may be a lot more unreliable on devices with AMD CPUs
  • You may have to get a machine running macOS to get your device to enter pwnDFU mode, or use iPwnder Lite for iOS

32-bit devices

  • To make sure that SSH is successful, try these steps
  • To devices with baseband, this script will restore your device with the latest baseband
  • This script can also be used to just enter kDFU mode for all supported devices
  • This script can work on virtual machines, but I will not provide support for them
  • If you get stuck in recovery mode after downgrading, or your device is unable to activate, try these steps:
  • There is an option to skip baseband update for downgrading. By default, this is enabled for iPad2,3; see here. This can be enabled for other devices by running restore.sh with --disable-bbupdate

Jailbreak Option for 32-bit devices

  • I have tested the Jailbreak Option successfully on iPad3,3 8.4.1, iPhone4,1 6.1.3 and 8.4.1, and iPhone5,2 8.4.1. Even if I have tested successfully on these, others may have varying results for some reason.
  • If you have problems with Cydia, remove the ultrasn0w repo, force close Cydia using the app switcher, then try opening Cydia again
  • If you cannot find Cydia in your home screen, try accessing Cydia through Safari with cydia:// and install "Jailbreak App Icons Fix" package from my Cydia repo: https://lukezgd.github.io/repo/
  • If you have problems with being unable to open Cydia, you may have to restore back to latest, downgrade again with the Jailbreak Option disabled, then sideload/jailbreak manually.
  • p0sixspwn will be used for iOS 6.1.3, and daibutsu for iOS 8.4.1
  • For devices jailbroken with daibutsu, add the system repo for future updates to the untether package: https://kok3shidoll.github.io/repo/
  • For devices jailbroken with daibutsu and want to use Coolbooter Untetherer, apply this fix/workaround using MTerminal (Legacy iOS Kit already applies this by default): 
    su
(enter password, default is 'alpine')
mkdir /taig
touch /taig/taig

Custom IPSW names

  • The custom IPSWs generated may have letter/s at the end of the file name. Here is a list of what each letter means.
  • A - Stitched activation records
  • B - Baseband update is disabled and stitched baseband enabled
  • G - gasgauge-patch flag is enabled
  • H - Hacktivate option is enabled
  • J - Jailbreak option is enabled
  • L - Custom logo and/or recovery image is used
  • N - NOR flash IPSW for powdersn0w (used for 4.2.1 and lower targets)
  • P - powdersn0w (7.1.x base)
  • P0 - powdersn0w (7.0.x base)
  • T - Tethered downgrade
  • V - Verbose boot option is enabled

DFU Advanced Menu for 32-bit devices

DFU Advanced Menu (A5(X) pwnDFU mode with Arduino and USB Host Shield)

DFU Advanced Menu (kDFU mode)

  • Select the "kDFU mode" option if your device is already in kDFU mode.
  • Example of this is selecting "Put Device in kDFU Mode" from the main menu, or using kDFUApp by tihmstar.
  • kDFUApp can be installed from my repo: https://lukezgd.github.io/repo/
  • For installation instructions, follow "All devices, jailbroken on iOS 9 or lower (alternative)"
  • Some devices are not supported by kDFUApp. To add support for more devices and iOS versions, make sure to also install "kDFUApp Bundles" from my repo
  • kDFUApp works on iOS versions 6.0 to 9.3.6. Other versions are not supported. Use Legacy iOS Kit's kDFU utility instead: Other Utilities -> Enter kDFU mode

Using manually saved SHSH blobs

  • Restoring to other versions with saved SHSH blobs is done with the "Other" Restore/Downgrade option. This will ask for the IPSW and SHSH files for the version that you want to downgrade to.
  • If you want to use other manually saved OTA (6.1.3/8.4.1) blobs, create a folder named saved, then within it create another folder named shsh. You can then put your blob inside that folder.
    • The naming of the blob should be: (ECID in Decimal)_(ProductType)_(Version)-(BuildVersion).shsh(2)
    • Example with path: saved/shsh/123456789012_iPad2,1_8.4.1-12H321.shsh
  • The BuildVersion for 6.1.3 is 10B329, 8.4.1 is 12H321, and 10.3.3 is 14G60

Clearing NVRAM

  • This can be done using the Clear NVRAM option in "Other Utilities."
  • For A5(X)/A6(X) devices, you can also do the following method below. Restore to the latest version first and jailbreak before proceeding.
  1. Jailbreak your device.
  2. Install MTerminal or NewTerm from Cydia/Zebra
  3. Run these commands (you may have to repeat this step a few times): 
    su
(enter password, default is 'alpine')
nvram -c
sync
  4. Then you may try to downgrade/restore again

Running wikiproxy

  • There are some cases that you may need to run wikiproxy for firmware keys. Here's how:
  1. Download this: https://github.com/LukeZGD/wikiproxy
  2. Make sure that you have Python 3 installed, cd to the directory and run: 
    python3 -m venv venv
venv/bin/python3 -m pip install -r requirements.txt
venv/bin/python3 wikiproxy.py
  3. Keep wikiproxy running. Run Legacy iOS Kit in another Terminal window

Scroll Back to Top

Clone this wiki locally