211 Troubleshooting
LukeeGD edited this page 2024-12-09 19:25:24 +08:00

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 or 3 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: try to re-install dependencies by deleting the firstrun file in the resources folder, 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.
    • Also try to restart your PC/Mac before retrying.
  • If your device is having issues restoring, try deleting any/all existing custom IPSWs before retrying.
  • If your device is having issues restoring on Linux, also try to run sudo killall usbmuxd usbmuxd2 before retrying.
  • Note for Apple Silicon Mac users: Better use a USB Dock than USB Dongle for connecting your devices. Since with dongles, the device needs a quick unplug and replug every time the device changes modes.
  • 32-bit devices: If the SSH step 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/flags

  • 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
  • The disable-bbupdate and dead-bb flags are not supported for restoring to latest iOS versions.
  • Warning: The "disable-bbupdate" flag does not always work in preserving baseband functionality. There is a chance of non-working baseband after the restore, so this option is considered as unreliable. Please do not enable this flag and use the latest baseband. Baseband version is pointless on these devices anyway.
  • All 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)
    --device=<type>           Specify device type
    --dfuhelper               Launch to DFU Mode Helper only
    --disable-sudoloop        Disable running tools as root for Linux
    --ecid=<ecid>             Specify device ECID
    --entry-device            Enable manual device type and ECID entry
    --exit-recovery           Attempt to exit recovery mode
    --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
    --pwn                     Pwn the connected device

For 32-bit devices compatible with restores/downgrades (see README):
    --activation-records      Enable dumping/stitching activation records
    --dead-bb                 Disable bbupdate completely without dumping/stitching baseband
    --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 (3GS and powdersn0w only)
    --jailbreak               Enable jailbreak option
    --just-boot               Tether boot the device (requires additional arguments)
    --memory                  Enable memory option for creating IPSW
    --pwned-recovery          Assume that device is in pwned recovery mode (experimental)
    --skip-first              Skip first restore and flash NOR IPSW only for powdersn0w 4.2.x and lower
    --skip-ibss               Assume that pwned iBSS has already been sent to the device

For 64-bit checkm8 devices compatible with pwned restores:
    --skip-blob               Enable futurerestore skip blob option for OTA/onboard/factory blobs
    --use-pwndfu              Enable futurerestore pwned restore option

    * Default IPSW path: <script location>/<name of IPSW file>.ipsw
    * Default SHSH path: <script location>/saved/shsh/<name of SHSH file>.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

  • Note for Apple Silicon Mac users: Better use a USB Dock than USB Dongle for connecting your devices. Since with dongles, the device needs a quick unplug and replug every time the device changes modes.
  • 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
      • This is sudo spctl --global-disable on newer versions of macOS (11 and newer)

Linux

  • checkm8 is unfortunately unreliable for A6/A7 devices on Linux, you may have to try multiple times.
  • You may also try in a live USB
  • If you have a PC with an AMD desktop CPU, this can significantly lower success rates of checkm8.
  • You may have to get a machine running macOS to get your device to enter pwnDFU mode, or use iPwnder Lite for iOS to continue the process on Linux
  • For advanced users: Hackintosh and macOS KVM with USB passthrough will 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 older, 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 older device 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
  • Because of Linux's low success rate with entering pwned DFU mode for A7 devices, 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
  • D - dead-bb flag is 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

  • For this section, A6(X) refers to iPhone 5 and iPad 4 devices, while A5(X) refers to the rest of the supported 32-bit devices.
  • Here are the other options 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 "Enter kDFU Mode" option of Legacy iOS Kit, 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. Make sure that you have Python 3 installed. Here's how:
  1. To install wikiproxy, use this command: python3 -m pip install git+https://github.com/m1stadev/wikiproxy.git
    • If the above command does not work, try this: python3 -m pip install --user --break-system-packages git+https://github.com/m1stadev/wikiproxy.git
  2. To run wikiproxy, use this command: wikiproxy
    • If this does not work, run source ~/.profile to attempt correcting $PATH
    • If this still does not work, use this command instead: ~/.local/bin/wikiproxy
  3. Keep wikiproxy running. Run Legacy iOS Kit in another Terminal window

Restoring to iPhoneOS/iOS 2.x on macOS

  • Note: This section can also help in detection issues of devices in Normal or Ramdisk/Restore mode. Just follow up to step 3 if this is the case.
  • To restore to 2.x on macOS, do the following in another terminal window:
  1. Install usbmuxd from MacPorts (it has to be from MacPorts, not Homebrew): sudo port install usbmuxd
  2. Run the following: sudo killall usbmuxd; sudo usbmuxd -pf
    • If you get usbmuxd not found error, fix your PATH to include /opt/local/bin
    • The output of which usbmuxd must be: /opt/local/bin/usbmuxd
  3. Keep usbmuxd running and go back to Legacy iOS Kit.
  4. Go to Restore/Downgrade -> Other (Custom IPSW) and select the 2.x IPSW
  5. Follow instructions on entering DFU/pwned DFU mode and let it restore. Done
  • Note: This will cause macOS to have USB detection issues on iOS devices after exiting usbmuxd. A reboot is needed to fix things