Troubleshooting

If your Mac is having trouble booting, here are some steps you can take to identify the problem and resolve it.

First, identify what happens when you power on the computer and jump to the appropriate section:

Changing the startup operating system

You can select which OS boots, either temporarily or permanently, by using the system’s built in Boot Picker. To do this, with the machine fully powered down:

  • Press and hold the power button

  • Keep holding until the screen reads "Entering startup options" (laptops, iMacs) or the power LED dims slightly (desktops), then release.

This will display the Boot Picker, where you can select the next operating system to boot. By default, the selection will be temporary. To make your choice permanent for all subsequent boots, click on the desired boot option while holding down the Option key on the keyboard.

You can also choose the rightmost "Options" icon to enter recoveryOS, which you can use to perform recovery operations. You may be prompted for your macOS login credentials, depending on the security state of your machine. Once at the main recoveryOS options screen, you can open a Terminal window by pressing Shift-Command-T.

Entering the GRUB boot menu

If there is a problem during a kernel package upgrade or some other issue that prevents the kernel from booting properly, you may need to enter the GRUB menu to select a different kernel or alter boot options.

Server and Minimal installs should show the GRUB menu by default. For desktop installs, you have to press Escape at the right time to enter the GRUB menu. When the system boots, you will see the display cycle through m1n1 (Asahi Linux or Fedora logos) and U-Boot (text screen with U-Boot logo on the top right). The U-Boot screen will show a brief countdown. Press Escape immediately after the countdown reaches 0 to enter the GRUB boot menu.

From there, you can choose an older kernel version (e.g. to recover from a failed kernel install), or change the boot options (e.g. to reset your password or recover from other system issues).

Troubleshooting U-Boot issues

U-Boot can have trouble with certain kinds of USB devices. If you are seeing strange behavior or logs from U-Boot, try disconnecting all USB devices (except a single keyboard, for desktop machines).

If you are having trouble getting an external keyboard to work in the U-Boot or GRUB menus, you may want to try using another USB port (e.g. Type C with an adapter instead of Type A) or a different keyboard. As U-Boot can only support a single keyboard, make sure no other USB devices that emulate a keyboard are connected. This includes some USB mice as well as certain USB tokens, barcode readers, etc. (YubiKeys should already be excluded and ignored in U-Boot).

Troubleshooting m1n1 stage 2 issues

If the m1n1 console is displayed and shows a Running proxy…​ message, this typically means that m1n1 stage 1 had trouble loading m1n1 stage 2.

If this occurred after a system update, it is possible that the new updated stage 2 binary was not installed correctly. You can boot into macOS or recoveryOS (see the Changing the startup operating system section) and perform the following steps to revert to the previous version of m1n1 stage 2 and U-Boot.

  1. Open a Terminal

  2. Type diskutil list | grep EFI to see the available EFI partitions

  3. The EFI partition will be named something similar to EFI - FEDOR. Make note of the identifier on the right, e.g. disk0sX.

  4. Type sudo diskutil mount disk0sX with the identifier you obtained above to mount the partition.

  5. Navigate to the mountpoint with cd "/Volumes/EFI - FEDOR" (replacing EFI - FEDOR with your volume name).

  6. Navigate to the m1n1 subdirectory: cd m1n1.

  7. List the files with ls. There should be a boot.bin file and a boot.bin.old file.

  8. Rename the current file to an inactive name: mv boot.bin boot.bin.new.

  9. Rename the old file to the active name: mv boot.bin.old boot.bin.

If you are running under macOS, you may also perform the file management steps with Finder. After mounting the partition with diskutil, it will appear in the Finder sidebar.

After reverting m1n1.bin, boot back into Fedora Asahi Remix to test the reverted version of m1n1 stage 2 and U-Boot.

Note that reverting the m1n1 stage 2 binary to the previous version is not guaranteed to work correctly, as sometimes there are incompatible device tree changes that accompany kernel version updates. You may find that some hardware does not work properly after the reversion. After a successful boot into Linux, you should run sudo update-m1n1 to update to the current version, and reboot again.

Upgrading or repairing m1n1 stage 1

Sometimes, the system’s Boot Policy for Fedora Asahi Remix might become corrupted. This sometimes occurs after macOS upgrades (due to bugs in Apple’s upgrade process). If this happens, attempting to boot that operating system will instead immediately reboot. If that OS is the default boot OS, the computer will reboot repeatedly until it triggers an OS recovery screen. If this happens, you need to restore m1n1 stage 1 and the associated Boot Policy.

It is also possible for a system firmware upgrade to trigger an incompatibility in m1n1 stage 1, requiring an update. This can happen if you update to macOS Sonoma 14.5 or later, with a m1n1 stage 1 older than 1.4.13 (released May 2024), due to a bug in those older m1n1 versions. To resolve this, update m1n1 stage 1.

The process for both of the above situations is the same. First, follow the steps in Changing the startup operating system to boot into recoveryOS (preferred) or macOS, and open a Terminal. Ensure you are connected to the internet, and then run the Fedora Asahi Remix installer again, using the instructions in the Installation page (or the steps available on asahilinux.org). Once the installer starts, one of the available options should be to Repair an incomplete installation (p) or Upgrade m1n1 on an existing OS (m). Choose the appropriate option and follow the instructions to upgrade or reinstall m1n1 stage 1.

Recovering an unbootable machine

If your machine is stuck displaying an exclamation mark icon (laptops and iMacs) or SOS LED blink pattern (desktops), you may need to perform a DFU Revive or Restore. To determine if this is necessary, first try to boot using both the current paired recoveryOS and the System recoveryOS.

To boot using the current recoveryOS:

  • Fully power down the machine

  • Press and hold the power button

  • Keep holding until the screen reads "Entering startup options" (laptops, iMacs) or the power LED dims slightly (desktops), then release.

To boot using the System RecoveryOS:

  • Fully power down the machine

  • Quickly press, release, and then press and hold the power button (the whole action should take less than half a second)

  • Keep holding until the screen reads "Entering startup options" (laptops, iMacs) or the power LED dims slightly (desktops), then release.

If either of those processes succeeds and shows the Boot Picker, you can choose an alternate OS to boot or select the "Options" icon to boot recoveryOS and troubleshoot the issue or reinstall another OS from that environment.

Performing a DFU revive or restore

If your machine fails to boot or enter Startup Options, you may have to perform a DFU Revive or Restore.

A DFU Revive will restore and update System Firmware and Recovery (SFR), while leaving operating systems and data intact. This may be able to resolve some issues, but is not guaranteed to work (e.g. a DFU Revive cannot recover a missing System Recovery partition, but it can reinstall recoveryOS into an existing but blank System Recovery partition with the appropriate subvolume).

A DFU Restore will completely wipe all data on the internal storage and restore the machine to factory condition. It is also the only way to downgrade System Firmware to a prior version. This process can recover from any kind of corruption or problem with the internal NVMe storage, and even corruption of the internal NOR Flash storage and several other firmware components. Note that if you perform a DFU Restore, you will lose all data stored on the machine, and it will be returned to its factory condition.

To perform a DFU Revive or Restore, you will need either another Mac running macOS, or a Fedora Linux machine (any hardware) with an available USB port. You will also need an appropriate USB cable to connect both machines together.

Performing a DFU revive or restore using another Mac running macOS

Follow Apple’s documentation to learn how to perform a restore using another Mac, using the macOS Finder or Apple Configurator.

If you have trouble putting the machine into DFU mode, you may also wish to refer to the instructions below.

Performing a DFU revive or restore using a machine running Fedora Linux

You can also boot Fedora Linux on another machine (Intel compatible or Apple Silicon both work), and then use idevicerestore to perform the DFU Revive or Restore process.

If you have a spare x86-64 (Intel/AMD) machine that does not currently have Fedora installed, you can follow the steps in the next section to temporarily live boot Fedora from a USB stick and set up the environment to be able to perform the DFU Revive/Restore. Once the system is up and running, return to this section to continue the process.

You will need a compatible USB cable. If your host machine has Type A ports, use a Type A to Type C cable. If your host machine has Type C ports, use a Type C to Type C cable. You may also use a Type A to Type C cable together with a female Type A to male Type C adapter. Your cable must support data transfer (USB 2.0 480Mbps is sufficient, though USB 3 cables also work). Thunderboot 3 cables will not work, nor will charge-only cables.

To perform a DFU Revive using a second Fedora machine, follow these steps:

  1. Ensure you are connected to the Internet.

    • On Fedora Workstation, click on the top right menu bar icon to select a WiFi network (if not using wired Ethernet).

  2. Open a Terminal.

    • On Fedora Workstation, click on the top left menu icon, type 'terminal' and hit Enter.

  3. Ensure you have at least 40GB of available disk space in the current working directory. If not, change to another directory that does or add additional storage as needed.

    • If you have followed the below steps to perform a live boot and configure your environment, this is already the case.

  4. Run the command sudo dnf install -y idevicerestore usbmuxd to install idevicerestore.

    • If the output indicates that usbmuxd was also installed as a dependency (and was not already installed), run sudo udevadm control --reload to reload the udev rules. Fedora Workstation live images should already have usbmuxd installed.

  5. Run the command sudo dmesg -w to show the live kernel log.

  6. Connect the USB cable between your host machine and the target machine to be restored. The cable must be connected to a specific USB port on the target machine:

    • For laptops, use the leftmost (rearmost) Type C port on the left side.

    • For iMacs, facing the rear of the machine, use the rightmost Type C port (closest to the power connector).

    • For Mac Mini machines, facing the rear of the machine, use the leftmost Type C port.

    • For Mac Studio machines, facing the rear of the machine, use the rightmost Type C port.

    • For Mac Pro desktop machines, facing the top of the machine, use the Type C port farthest from the power button.

    • For Mac Pro rackmount machines, facing the front of the machine, use the Type C port closest to the power button.

    If you are using a Type A to Type C cable, connect the Type C end to the target machine. The Type A end may be directly connected to the host machine, or to a Type C port via a Type A to Type C adapter. USB hubs may also be used on the host machine side (but not the target machine side).

  7. Enter DFU mode. The process is different for desktops and laptops (you can pick one of two options for laptops; try both if you have trouble getting it to work).

    • For desktops:

      1. Start with the machine fully powered down.

      2. Unplug the machine from the mains power and wait 30 seconds.

      3. Press and hold down the power button.

      4. While holding down the power button, connect mains power to the machine.

      5. Continue holding down the power button and watch the kernel log. Look for a USB device log that mentions Product: Apple Mobile Device (DFU Mode).

      6. Once you see the log, release the power button.

    • For laptops (method 1):

      1. Start with laptop fully powered down.

      2. Press and release the power button quickly.

      3. Immediately press and hold the following keys: Left control, left option, right shift, and the power button.

      4. Count down 10 seconds, then release everything except the power button.

      5. Continue holding down the power button and watch the kernel log. Look for a USB device log that mentions Product: Apple Mobile Device (DFU Mode).

      6. Once you see the log, release the power button.

    • For laptops (method 2):

      1. Start with laptop powered up (make sure something is visible on the display).

      2. Press and hold the following keys: Left control, left option, right shift, and the power button.

      3. Wait until the screen turns off, then count down 5 additional seconds, then release everything except the power button.

      4. Continue holding down the power button and watch the kernel log. Look for a USB device log that mentions Product: Apple Mobile Device (DFU Mode).

      5. Once you see the log, release the power button.

    If you don’t see the DFU device in the log, or the Product mentions "Recovery Mode" instead, something went wrong. Retry the steps again. The display of the target machine will remain blank in DFU mode.

  8. On your host machine, press Ctrl-C to stop the dmesg command.

  9. Run the following command: systemd-inhibit sudo -s TMPDIR=$PWD idevicerestore -l.

  10. When prompted, type '1' to select the latest available macOS/firmware version.

During the Restore process, the target machine will display an Apple logo and a progress bar, while the host machine running idevicerestore will print out progress log information. Note that this process involves connecting to Apple’s CDN and servers to download system firmware components and authenticate them for your specific machine.

After the process completes successfully, the machine will reboot into the Recovery Assistant. Follow the prompts to select a macOS volume to recover, and enter your macOS authentication credentials. After this process succeeds, your machine will boot into the Boot Picker. From here, you can choose which OS to boot next.

It is likely that any existing Fedora Asahi Remix installations will become unbootable as a result of the Revive process. If attempting to boot a Linux install triggers a reboot or a Recovery screen, follow the steps in the Upgrading or repairing m1n1 stage 1 section to reinstall m1n1 stage 1 and make the OS bootable again.

If the DFU Revive fails, you will have to perform a DFU Restore. To do so, follow the above steps again, but add the -e option to the idevicerestore command:

systemd-inhibit sudo -s TMPDIR=$PWD idevicerestore -l -e

This will irreversibly wipe all data on the target machine.

After a DFU Restore, your machine will be reset to its factory condition and boot into the macOS first-time setup wizard.

Live booting Fedora Linux on an x86 (Intel/AMD) compatible machine to perform a DFU restore

You can use a USB disk to live-boot Fedora Workstation on any x86-64 machine and perform the DFU restore from that environment, without having to install to local disk. You will need a USB disk with at least 64GB of capacity.

All existing data on the USB disk will be erased.

To set up the USB disk, we recommend using Fedora Media Writer. Follow the steps on that page to download it and write the image to your USB disk, and then boot it on your target machine.

Once the system is booted, follow the following steps to open up a terminal:

  1. On 'Welcome to Fedora' screen, click 'Not Now'.

  2. Click on the top right menu bar icon and connect to a WiFi network (if not using wired Ethernet).

  3. Click on the top left menu icon, type 'terminal' and hit enter.

To perform the DFU Restore process, idevicerestore needs a large amount of temporary disk space. Since the live image runs from RAM, it does not have enough temporary space available. To create and use a temporary partition in the remaining free space on the USB disk, run the following commands one by one:

device=$(grep /run/initramfs/live /proc/mounts | awk '{ print $1 }' | sed 's/[0-9]*$//')
echo "size=40G" | sudo sfdisk -a $device
sudo partprobe $device
part=$(ls ${device}[0-9] | tail -n 1)
sudo mkfs.ext4 $part
sudo mkdir -p /mnt/tmp
sudo mount $part /mnt/tmp
sudo chmod 777 /mnt/tmp
cd /mnt/tmp

Next, continue with the steps in the Performing a DFU revive or restore using a machine running Fedora Linux section (you have already performed steps 1-3 and do not need to do them again).

Want to help? Learn how to contribute to Fedora Docs ›