> ## Documentation Index
> Fetch the complete documentation index at: https://docs.derekdinh.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot macOS Startup Failures and Boot Loops

> Diagnose and fix Mac startup failures including spinning beach balls, stuck Apple logos, and boot loops using built-in macOS recovery tools.

When your Mac refuses to start normally, the cause can range from a minor firmware glitch to a corrupted system file or failing hardware component. Working through a structured sequence of resets and diagnostics — from NVRAM clears to Disk Utility's First Aid — resolves the vast majority of startup problems without data loss or a visit to an Apple Authorized Service Provider.

## Common Startup Symptoms

Before diving into fixes, identify which symptom your Mac is showing so you can target the most effective solution first.

<AccordionGroup>
  <Accordion title="Spinning beach ball at startup (stuck on gray/dark screen)">
    The system loads the bootloader but stalls before reaching the login screen. This is most commonly caused by a corrupted preference file, a problem with a login item, or a disk error.
  </Accordion>

  <Accordion title="Stuck Apple logo with progress bar that never completes">
    macOS begins loading but the kernel or a system extension fails to initialize. Safe Mode and Disk Utility First Aid are your first tools here.
  </Accordion>

  <Accordion title="Flashing question-mark folder">
    The firmware cannot find a valid startup disk. The internal drive may have become unmounted, failed, or the startup disk selection has been lost from NVRAM.
  </Accordion>

  <Accordion title="Continuous restart loop (boot loop)">
    A kernel panic is occurring repeatedly. This often points to a recently installed kernel extension, a third-party driver, or a hardware fault.
  </Accordion>
</AccordionGroup>

***

## Step-by-Step Troubleshooting

<Steps>
  <Step title="Perform a Hard Shutdown and Cold Boot">
    Before attempting any recovery procedure, rule out a transient software hang by forcing a clean power cycle.

    1. Hold the **power button** for 10 seconds until the Mac shuts off completely.
    2. Wait **30 seconds** to allow capacitors to discharge.
    3. Press the power button once to restart.

    <Tip>
      On MacBooks, disconnect all external peripherals (USB hubs, external displays, docks) before rebooting. A faulty peripheral can prevent startup.
    </Tip>

    If the Mac boots normally, monitor it for recurrence. If the problem persists, continue to the next step.
  </Step>

  <Step title="Reset NVRAM / PRAM">
    NVRAM (Non-Volatile RAM) stores low-level settings such as the selected startup disk, screen resolution, and time zone. Corruption in NVRAM can cause persistent startup failures.

    <Tabs>
      <Tab title="Intel Mac">
        1. Shut down your Mac completely.
        2. Press the power button, then **immediately** hold **Option + Command + P + R**.
        3. Keep holding all four keys for **at least 20 seconds** (you will hear the startup chime twice on older models, or see the Apple logo appear and disappear twice on newer models).
        4. Release the keys and allow the Mac to boot normally.

        ```bash theme={null}
        # After rebooting, verify the startup disk is correctly set:
        # Apple Menu → System Preferences → Startup Disk
        ```
      </Tab>

      <Tab title="Apple Silicon (M1/M2/M3)">
        Apple Silicon Macs do not have NVRAM in the traditional sense — it is reset automatically as needed. Instead, shut down the Mac, wait 30 seconds, and power it back on.

        <Note>
          If you suspect firmware-level settings are corrupted on Apple Silicon, use **Startup Security Utility** in macOS Recovery to restore default security settings.
        </Note>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Reset the System Management Controller (SMC)">
    The SMC handles power management, thermal control, and hardware button behavior. A corrupted SMC state can prevent your Mac from completing the boot process.

    <Tabs>
      <Tab title="MacBook with T2 chip (2018–2020)">
        1. Shut down the MacBook.
        2. Hold **Control + Option (left) + Shift (right)** for 7 seconds. The Mac may power on — keep holding.
        3. Add the **power button** to the held keys and continue holding all four for another 7 seconds.
        4. Release all keys, wait 5 seconds, then press the power button to start normally.
      </Tab>

      <Tab title="MacBook without T2 (pre-2018)">
        1. Shut down the MacBook and connect the MagSafe/USB-C power adapter.
        2. Hold **Shift + Control + Option** on the left side of the keyboard and press the **power button** simultaneously.
        3. Hold for 10 seconds, then release all keys.
        4. Press the power button to start.
      </Tab>

      <Tab title="Desktop Mac (iMac, Mac Pro, Mac mini)">
        1. Shut down the Mac and **unplug the power cable**.
        2. Wait **15 seconds**.
        3. Reconnect the power cable, wait 5 seconds, then press the power button.
      </Tab>

      <Tab title="Apple Silicon Mac">
        Apple Silicon Macs do not have a separate SMC. Shut down, unplug all cables for 30 seconds, reconnect, and power on.
      </Tab>
    </Tabs>

    <Note>
      After an SMC reset, settings like keyboard backlighting behavior and fan curves return to defaults. This is expected and not a sign of additional problems.
    </Note>
  </Step>

  <Step title="Boot in Safe Mode">
    Safe Mode starts macOS with only essential kernel extensions loaded and automatically runs a basic directory check on your startup disk. It also clears certain system caches.

    <Tabs>
      <Tab title="Intel Mac">
        1. Shut down your Mac.
        2. Power on, then **immediately hold the Shift key**.
        3. Release Shift when you see the login window. The words **"Safe Boot"** appear in red in the top-right corner of the login screen.
      </Tab>

      <Tab title="Apple Silicon Mac">
        1. Shut down your Mac.
        2. Press and hold the **power button** until "Loading startup options" appears.
        3. Select your startup disk, then hold **Shift** and click **Continue in Safe Mode**.
      </Tab>
    </Tabs>

    Once in Safe Mode:

    * Check whether the startup issue is resolved. If the Mac boots cleanly in Safe Mode but not normally, a **third-party login item or kernel extension** is the culprit.
    * Navigate to **System Settings → General → Login Items** and disable all non-Apple startup items. Re-enable them one at a time to identify the offender.

    ```bash theme={null}
    # From Terminal in Safe Mode, list all launch agents and daemons:
    ls /Library/LaunchAgents/
    ls /Library/LaunchDaemons/
    ls ~/Library/LaunchAgents/
    ```

    <Tip>
      To remove a problematic launch daemon without knowing its exact name, drag it out of the `/Library/LaunchDaemons/` folder to the Desktop and reboot normally.
    </Tip>
  </Step>

  <Step title="Run First Aid in Disk Utility (Recovery Mode)">
    If the Mac still will not boot normally, boot into macOS Recovery to run Disk Utility's First Aid, which checks and repairs the file system.

    <Tabs>
      <Tab title="Intel Mac — Enter Recovery">
        1. Restart your Mac.
        2. Immediately hold **Command + R** until the Apple logo appears.
        3. Release the keys and wait for the macOS Utilities window.
      </Tab>

      <Tab title="Apple Silicon Mac — Enter Recovery">
        1. Shut down your Mac completely.
        2. Press and hold the **power button** until "Loading startup options" appears.
        3. Click **Options**, then click **Continue**.
      </Tab>
    </Tabs>

    Once in Recovery Mode:

    1. Select **Disk Utility** from the macOS Utilities menu and click **Continue**.
    2. In the sidebar, select your **startup volume** (typically named "Macintosh HD"). If you see both "Macintosh HD" and "Macintosh HD – Data", run First Aid on both, starting with "Macintosh HD – Data".
    3. Click **First Aid**, then **Run**.

    ```bash theme={null}
    # Alternatively, run fsck from Terminal in Recovery Mode:
    # Select Terminal from the Utilities menu, then:
    diskutil list                        # identify your disk identifier
    diskutil repairVolume /dev/disk3s1   # replace disk3s1 with your volume
    ```

    <Warning>
      Do not interrupt First Aid once it has started. Stopping mid-repair can leave the file system in a worse state than before. If your Mac's battery is low, plug in power before proceeding.
    </Warning>

    4. If First Aid reports **"The volume could not be repaired"**, the file system damage is beyond what Disk Utility can fix automatically. Proceed to reinstalling macOS.
  </Step>

  <Step title="Reinstall macOS Without Erasing Data">
    Reinstalling macOS over an existing installation repairs all Apple-supplied system files without touching your personal files, applications, or settings.

    1. Boot into **Recovery Mode** (see Step 5 above).
    2. Select **Reinstall macOS \[version name]** from the macOS Utilities menu.
    3. Click **Continue** and follow the on-screen prompts.
    4. When prompted to choose a disk, select **Macintosh HD** (do **not** select the Data volume).
    5. The installer downloads macOS from Apple's servers (\~12 GB) and installs it. This typically takes 45–90 minutes depending on your internet connection.

    <Note>
      An internet connection is required for this process. Recovery Mode connects via Wi-Fi or Ethernet; select your network when prompted if using Wi-Fi.
    </Note>

    <Warning>
      Although this process preserves your data, **back up with Time Machine before proceeding** if at all possible. Boot from an external drive or use Target Disk Mode to back up if the Mac won't reach the login screen.
    </Warning>

    After reinstallation, the Mac will reboot into the normal setup or login flow. Your files and applications will be intact.
  </Step>
</Steps>

***

## Escalation

If none of the steps above restore normal startup behavior, the issue is likely beyond software-level repair.

<AccordionGroup>
  <Accordion title="When to escalate to hardware diagnostics">
    Run **Apple Diagnostics** (hold **D** at startup on Intel Macs, or hold the power button on Apple Silicon Macs and select the diagnostics option) to check for hardware faults in memory, storage, or the logic board. Note any reference codes returned (e.g., `NDN001` for NVMe storage issues) and provide them to support staff.
  </Accordion>

  <Accordion title="Signs of a failing internal drive">
    Repeated First Aid failures, S.M.A.R.T. status showing "Failing" in Disk Utility, or error codes such as `NVMeSMART` from Apple Diagnostics indicate the internal SSD is failing and must be replaced by an Apple Authorized Service Provider.
  </Accordion>

  <Accordion title="Escalation path">
    1. Document all steps attempted and their outcomes.
    2. Note any Apple Diagnostics reference codes.
    3. Submit a ticket to your IT helpdesk or contact **Apple Support** at [support.apple.com](https://support.apple.com).
    4. If the device is under AppleCare+ or a corporate device management agreement, arrange depot repair through your IT asset management team.
  </Accordion>
</AccordionGroup>