From 2d6d1f0235851f9c445f65bb48e2d2537fe9657d Mon Sep 17 00:00:00 2001 From: neon ball <35791009+ParaDoX1994@users.noreply.github.com> Date: Thu, 7 Aug 2025 23:01:10 +0300 Subject: [PATCH] Overhaul Troubleshooting categorization Separate hardware issues to own section as well and rename sites with better consistency. --- docs/TROUBLESHOOT-APP.md | 122 ++++++++++++++++ docs/TROUBLESHOOT-HARDWARE.md | 266 ++++++++++++++++++++++++++++++++++ docs/TROUBLESHOOT-MISC.md | 143 ++++++++++++++++++ docs/TROUBLESHOOT-NONMETAL.md | 114 +++++++++++++++ 4 files changed, 645 insertions(+) create mode 100644 docs/TROUBLESHOOT-APP.md create mode 100644 docs/TROUBLESHOOT-HARDWARE.md create mode 100644 docs/TROUBLESHOOT-MISC.md create mode 100644 docs/TROUBLESHOOT-NONMETAL.md diff --git a/docs/TROUBLESHOOT-APP.md b/docs/TROUBLESHOOT-APP.md new file mode 100644 index 000000000..3ac02d9d1 --- /dev/null +++ b/docs/TROUBLESHOOT-APP.md @@ -0,0 +1,122 @@ +# Application issues + +* [OpenCore Legacy Patcher not launching](#opencore-legacy-patcher-not-launching) +* [Privileged Helper Tool not found](#privileged-helper-tool-not-found) +* ["You don't have permission to save..." error when creating USB installer](#you-don-t-have-permission-to-save-error-when-creating-usb-installer) +* [Internal disk missing when building OpenCore](#internal-disk-missing-when-building-opencore) +* ["Unable to resolve dependencies, error code 71" when root patching](#unable-to-resolve-dependencies-error-code-71-when-root-patching) +* [System version mismatch error when root patching](#system-version-mismatch-error-when-root-patching) + + +## OpenCore Legacy Patcher not launching + +If the application won't launch (e.g. icon will bounce in the Dock), try launching OCLP via Terminal by typing the following command. + +```sh +/Library/Application Support/Dortania/OpenCore-Patcher.app/Contents/MacOS/OpenCore-Patcher +``` + +## Privileged Helper Tool not found + +OCLP needs a Privileged Helper Tool to run parts of the application as root. If you encounter this error, reinstall OCLP using the PKG installer* to fix Privileged Helper Tool. + + * In OCLP 2.3.0 and newer, using PKG is the only way to install and app.zip method has been discontinued. + +## "You don't have permission to save..." error when creating USB installer + +In some cases, a following error saying "The bless of the installer disk failed" stating the reason as "You don't have permission to save..." may appear. + + +
+ NoPermissionToSave +
+ + +To resolve this, you may try adding Full Disk Access permission for OpenCore Legacy Patcher. To add it, first go to the settings + +* Ventura and Sonoma: Go to System Settings -> Privacy and Security -> Full Disk Access + +* Big Sur and Monterey: Go to System Preferences -> Security and Privacy -> Full Disk Access + +Enable OpenCore-Patcher in the list. If not found on the list, press the + sign to add a new entity and find OpenCore Legacy Patcher from Applications. + +Restart OpenCore Legacy Patcher and try creating your USB drive again. + +Optional: After you've created your USB drive, you can remove OpenCore Legacy Patcher from Full Disk Access again. + +## Internal disk missing when building OpenCore + +If you're using a brand new disk that has not been used before or was never formatted in any macOS type, you may face the following error in OCLP when trying to build on the internal disk. + +
+ Failed to find applicable disks +
+ +There are two ways to to try and resolve this. + +1. Create a new FAT32 partition using Disk Utility, sized at around 100MB, naming does not matter. OpenCore will detect it and you will be able to build your EFI there. + +2. When installing macOS, choose "View -> Show all devices" in Disk Utility and format the entire disk by choosing the topmost option in the sidebar. + +
+ Wipe disk +
+ +## "Unable to resolve dependencies, error code 71" when root patching + +If you're getting this error, it typically means you have some offending kernel extensions, to fix this you will have to clear them. + +Semi-automated way: + +1. Open Terminal +2. Type `sudo zsh` +3. Type `cd "/Volumes/Macintosh HD/Library/Extensions" && ls | grep -v "HighPoint*\|SoftRAID*" | xargs rm -rf` + * Make sure to rename "Macintosh HD" to what your drive name is +4. Run OCLP root patcher again + +Manual way: + +1. Navigate to /Library/Extensions +2. Delete everything **except** HighPointIOP.kext, HighPointRR.kext and SoftRAID.kext +3. Run OCLP root patcher again + +If there is no success, navigate to "/Library/Developer/KDKs" and delete everything. + +If still no success, type `sudo bless --mount "/Volumes/Macintosh HD/" --bootefi --last-sealed-snapshot` +* Make sure again to rename "Macintosh HD" to what your drive name is + +Run OCLP root patcher again. + +## System version mismatch error when root patching + +Due to a change by Apple, updates now modify the system volume **already while downloading**, which can lead to broken patches out of a sudden, since the operating system gets into a liminal state between two versions. Hence while root patching, you may get an error that looks like the following: + +`SystemVersion.plist build version mismatch: found 15.4 (24E247), expected 13.7.5 (22H527)` + +In this example, it is telling that a version 13.7.5 (Ventura) is expected which is currently running but macOS has already staged an update to version 15.4 (Sequoia) and has already modified the filesystem to prepare for an update, including writing the new version in SystemVersion.plist where OCLP is able to read it from. The "version mismatch" error is a safeguard preventing OCLP from patching on a system that is in a weird liminal state, to avoid leading to a very likely boot failure. + +There are few options to resolve it: + +1. Update/upgrade to the version already staged. +2. Reinstall macOS. + * You can try doing an in-place install without wiping the disk to keep your data but this may not be possible due to the OS being partially on newer version and it will complain about downgrade. +4. Use an experimental "PurgePendingUpdate" tool [from the Discord server](https://discord.com/channels/417165963327176704/1253268648324235345/1257348959454625985). + * Download it and then run it in Terminal to get rid of a pending update, then repatch again. If "purge failed" appears, you can ignore it. + * Sometimes you may have to give the file an execution permission with `chmod +x` and putting the application path after the command (type or drag the file) before the tool can be ran. + * This may be integrated into OCLP later on, however there is currently no ETA. + +**Disabling automatic macOS updates is extremely recommended once recovered, to prevent it from happening again.** + +* Note: macOS Sequoia has begun prompting to enable automatic updates from 15.4 onward after an update install has finished and isn't giving a choice to fully decline, this means you may have to keep doing it again after updating to newer versions. + +::: details How to disable updates (click to expand) + +**macOS Ventura and newer:** + +System Settings -> General -> Software Update -> (i) button next to Automatic Updates -> Disable "Download new updates when available". + +**macOS Big Sur and Monterey:** + +System Preferences -> Software Update -> Advanced -> Disable "Download new updates when available". + +::: diff --git a/docs/TROUBLESHOOT-HARDWARE.md b/docs/TROUBLESHOOT-HARDWARE.md new file mode 100644 index 000000000..fa59e3012 --- /dev/null +++ b/docs/TROUBLESHOOT-HARDWARE.md @@ -0,0 +1,266 @@ +## Hardware issues + +**General** + +* [No Brightness Control](#no-brightness-control) +* [Cannot connect Wi-Fi on Monterey with legacy cards](#cannot-connect-wi-fi-on-monterey-with-legacy-cards) +* [No Graphics Acceleration](#no-graphics-acceleration) +* [No DisplayPort Output on Mac Pros with NVIDIA Kepler](#no-displayport-output-on-mac-pros-with-nvidia-kepler) +* [Secondary CPU not visible on MacPro3,1/Xserve2,1](#secondary-cpu-not-visible-on-macpro3-1-xserve2-1) +* [No acceleration after a Metal GPU swap on Mac Pro](#no-acceleration-after-a-metal-gpu-swap-on-mac-pro) +* [Keyboard, Mouse and Trackpad not working in installer or after update](#keyboard-mouse-and-trackpad-not-working-in-installer-or-after-update) +* [No T1 functionality after installing Sonoma or newer](#no-t1-functionality-after-installing-sonoma-or-newer) + +**Non-Metal** + + +* [Keyboard Backlight broken](#keyboard-backlight-broken) +* [Wake from sleep heavily distorted on AMD/ATI from macOS 11.3 to Monterey](#wake-from-sleep-heavily-distorted-on-amd-ati-from-macos-11-3-to-monterey) +* [Unable to switch GPUs on 2011 15" and 17" MacBook Pros](#unable-to-switch-gpus-on-2011-15-and-17-macbook-pros) +* [Erratic Colours on ATI TeraScale 2 GPUs (HD5000/HD6000)](#erratic-colours-on-ati-terascale-2-gpus-hd5000-hd6000) +* [Cannot Login on 2011 15" and 17" MacBook Pros](#cannot-login-on-2011-15-and-17-macbook-pros) +* [Black Boxes on HD3000 iGPUs](#black-boxes-on-hd3000-igpus) +* [Cannot Pair Bluetooth Devices](#cannot-pair-bluetooth-devices) + +For those unfamiliar with what is considered a non-Metal GPU, see the chart below: + +::: details macOS GPU Chart + +Metal is Apple's in-house graphics API that acts as a replacement for OpenGL/OpenCL, introduced in 2015. With the release of macOS Mojave, every system without a Metal-capable GPU was dropped. + +| Graphics Vendor | Architecture | Series | Supports Metal | +| :--- | :--- | :--- | :--- | +| ATI | TeraScale 1 | HD 2XXX - HD 4XXX | No | +| ^^ | TeraScale 2 | HD 5XXX - HD 6XXX | ^^ | +| AMD | GCN (and newer) | HD 7XXX+ | Yes | +| NVIDIA | Tesla | 8XXX - 3XX | No | +| ^^ | Fermi | 4XX - 5XX | ^^ | +| ^^ | Kepler | 6XX - 7XX | Yes | +| ^^ | Maxwell | 8XX - 9XX | No (on 10.14 and newer) | +| ^^ | Pascal | 10XX | ^^ | +| Intel | GMA | GMA 900 - GMA X3000 | No | +| ^^ | Iron Lake | HD series | ^^ | +| ^^ | Sandy Bridge | HD 3000 | ^^ | +| ^^ | Ivy Bridge (and newer) | HD 4000 | Yes + +::: + +## No Brightness Control + +With OCLP v0.0.22, we've added support for brightness control on many models. However, some users may have noticed that their brightness keys do not work. + +As a work-around, we recommend users try out the below app: + +* [Brightness Slider](https://actproductions.net/free-apps/brightness-slider/) + +## Cannot connect Wi-Fi on Monterey with legacy cards + +With OCLP v0.2.5, we've added support for legacy Wi-Fi on Monterey. However, some users may have noticed that they can't connect to wireless networks. + +To work-around this, we recommend that users manually connect using the "Other" option in the Wi-Fi menu bar or manually adding the network in the "Network" preference pane. + +## No Graphics Acceleration + +In macOS, GPU drivers are often dropped from the OS with each major release of it. With macOS Big Sur, currently, all non-Metal GPUs require additional patches to gain acceleration. In addition, macOS Monterey removed Graphics Drivers for both Intel Ivy Bridge and NVIDIA Kepler graphics processors. + +If you're using OCLP v0.4.4, you should have been prompted to install Root Volume patches after the first boot from installation of macOS. If you need to do this manually, you can do so within the patcher app. Once rebooted, acceleration will be re-enabled as well as brightness control for laptops. + +## No DisplayPort Output on Mac Pros with NVIDIA Kepler + +If you're having trouble with DisplayPort output on Mac Pros, try enabling Minimal Spoofing in Settings -> SMBIOS Settings and rebuild/install OpenCore. This will trick macOS drivers into thinking you have a newer MacPro7,1 and resolve the issue. + + +
+ GUI SMBIOS minimal +
+ + +## Intermediate issues with USB 1.1 and Bluetooth on MacPro3,1 - MacPro5,1 + +For those experiencing issues with USB 1.1 devices (such as mice, keyboards and bluetooth chipsets), macOS Big Sur and newer have weakened OS-side reliability for the UHCI controller in older Mac Pros. + +* UHCI is a USB 1.1 controller that is hooked together with the USB 2.0 ports in your system. Whenever a USB 1.1 device is detected, the UHCI controller is given ownership of the device at a hardware/firmware level. + * EHCI is the USB 2.0 controller in older Mac Pros + +Because of this, we recommend placing a USB 2.0/3.0 hub between your devices and the port on the Mac Pro. UHCI and EHCI cannot both be used at once, so using a USB hub will always force the EHCI controller on. + +* Alternatively, you can try cold-starting the hardware and see if macOS recognizes the UHCI controller properly. + + +## Secondary CPU not visible on MacPro3,1/Xserve2,1 + +Starting with macOS Sequoia, OCLP has to disable the secondary CPU in these systems to avoid a panic. This also means by default, only single CPU will be usable even on older versions. To re-enable both CPUs on older versions, do the following: + +1. Open Settings -> `Build` tab. +2. Untick `MacPro3,1/Xserve2,1 Workaround`. +3. Rebuild OpenCore. +4. Reboot. + +**Dual CPUs cannot be enabled in any circumstance if Sequoia or newer is installed, even in multiboot scenarios. Doing so will make Sequoia unbootable.** + +[More information here](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1136#:~:text=we%20cannot%20verify.-,MacPro3%2C1%20Dual%20Socket%20Support,-Currently%20on%20macOS) + +## No acceleration after a Metal GPU swap on Mac Pro + +If you finished installing macOS with the original card installed (to see bootpicker for example) and swapped your GPU to a Metal supported one, you may notice that you're missing acceleration. To fix this, open OCLP and revert root patches to get your Metal-supported GPU work again. In macOS Ventura and newer, repatching is needed after reversion. + +Alternatively, you can remove "AutoPkg-Assets.pkg" from /Library/Packages on the USB drive before proceeding with the installation. To see the folder, enable hidden files with `Command` + `Shift` + `.` + +The reason for this is that the autopatcher will assume that you will be using the original graphics card and therefore does non-metal patching, which includes removing some drivers for other cards. This causes Metal cards to not accelerate after swapping. + +## Keyboard, Mouse and Trackpad not working in installer or after update + +Starting from macOS Ventura, USB 1.1 drivers are no longer provided in the operating system. For Macs using legacy USB 1.1 controllers, OpenCore Legacy Patcher can only restore support once it has performed root volume patches which restore the drivers. Thus when installing macOS or after an update, you need to hook up a USB hub between your Mac and keyboard/mouse, forcing USB 2.0 mode in order to install the root patches. + +* For MacBook users, you'll need to find an external keyboard/mouse in addition to the USB hub + +Applicable models include: + +| Family | Year | Model | Notes | +| :---------- | :--------------------| :---------------------------- | :----------------------------------------------- | +| MacBook | Mid 2010 and older | MacBook5,1 - MacBook7,1 | | +| MacBook Air | Late 2010 and older | MacBookAir2,1 - MacBookAir3,x | | +| MacBook Pro | Mid 2010 and older | MacBookPro4,1 - MacBookPro7,x | Excludes Mid 2010 15" and 17" (MacBookPro6,x) | +| iMac | Late 2009 and older | iMac7,1 - iMac10,x | Excludes Core i5/7 27" late 2009 iMac (iMac11,1) | +| Mac mini | Mid 2011 and older | Macmini3,1 - Macmini5,x | | +| Mac Pro | Mid 2010 and older | MacPro3,1 - MacPro5,1 | | + + +
+ USB1.1 chart +
+ +::: warning Note + +In macOS Sonoma, this seems to have been further weakened and some hubs may not be functional. If you encounter this issue, try another hub. + +::: + +### Alternative method for Software Update + +Alternative way for updates is making sure to enable "Remote Login" in General -> Sharing before updating, which will enable SSH. That means you can take control using Terminal in another system and run Post Install Volume Patching. + +**This only applies to updates via Software Update and is not applicable when booting to installer via USB drive.** + +Use the following commands: + +1. `ssh username@lan-ip-address` - Connects via SSH, change username and IP address to the system's +2. `/Applications/OpenCore-Patcher.app/Contents/MacOS/OpenCore-Patcher --patch_sys_vol` - Installs root patches via CLI +3. `sudo reboot`. + +More information can be found here: + +* [Legacy UHCI/OHCI support in Ventura #1021](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1021) + + +## No T1 functionality after installing Sonoma or newer + +If you notice your Touchbar etc not working, this means loss of T1 functionality. + +Wiping the entire disk using Disk Utility with Sonoma or newer causes the T1 firmware to be removed, which due to removed support, the macOS Sonoma+ installer will not restore. If the firmware is missing from EFI, T1 will not work regardless whether OCLP reinstates the driver during root patching. To restore T1 functionality, Ventura or older has to be reinstalled. This can be done in another volume or external disk as well, as long as the OS is booted once. After this you can wipe the old OS or unplug the external disk. + + +To prevent this from happening in the future, with T1 systems only wipe the volume containing the operating system. + +
+ WipeVolume +
+ + + + +## Keyboard Backlight broken + +Due to forcing `hidd` into spinning up with the fallback mode enabled, this can break the OS's recognition of backlight keyboards. Thankfully the drivers themselves still do operate so applications such as [LabTick](https://www.macupdate.com/app/mac/22151/lab-tick) are able to set the brightness manually. + +::: details For Big Sur (click to expand) + +Due to the Metal Backend, the enhanced color output of these apps seems to heavily break overall UI usage. To work around this, [users reported](https://forums.macrumors.com/threads/macos-11-big-sur-on-unsupported-macs-thread.2242172/post-29870324) forcing the color output of their monitor from Billions to Millions of colors helped greatly. Apps easily allowing this customization are [SwitchResX](https://www.madrau.com), [ResXreme](https://macdownload.informer.com/resxtreme/) and [EasyRes](http://easyresapp.com). + +::: + +## Wake from sleep heavily distorted on AMD/ATI from macOS 11.3 to Monterey + +**Fixed for macOS Ventura starting from 0.6.6. Big Sur and Monterey will continue to exhibit the issue.** + +For older versions, only known solution is to downgrade to macOS 11.2.3 or older. Additionally, logging out and logging back in can resolve the issue without requiring a reboot. + +* Note, this issue should be exclusive to TeraScale 1 GPUs (ie. HD2000-4000). TeraScale 2 GPUs should not exhibit this issue. + +In the event Apple removes 11.2.3 from their catalogue, we've provided a mirror below: + +* [Install macOS 11.2.3 20D91](https://archive.org/details/install-mac-os-11.2.3-20-d-91) + +## Unable to switch GPUs on 2011 15" and 17" MacBook Pros + +Currently, with OpenCore Legacy Patcher, GPU switching between the iGPU and dGPU is broken. The simplest way to set a specific GPU is to disable the dGPU when you wish to remain on the more power efficient iGPU. + +The best way to achieve this is to boot to Recovery (or Single User Mode if the dGPU refuses to function at all) and run the following command: + +```sh +nvram FA4CE28D-B62F-4C99-9CC3-6815686E30F9:gpu-power-prefs=%01%00%00%00 +``` + +This will disable the dGPU and allow the iGPU to function in Big Sur. Note that external display outputs are directly routed to the dGPU and therefore can no longer be used. Solutions such as [DisplayLink Adapters](https://www.displaylink.com/products/usb-adapters) can work around this limitation, however, note that you'll need to use older drivers (5.2.6): + +* [DisplayLink USB Graphics Software for macOS - For Mojave and Catalina - 5.2.6](https://www.synaptics.com/products/displaylink-graphics/downloads/macos-5.2.6) + +Note: This driver only provides partial support in macOS, full graphics acceleration is not currently available on displays driven by DisplayLink. + + +## Erratic Colours on ATI TeraScale 2 GPUs (HD5000/HD6000) + +Resolved with OpenCore Legacy Patcher v0.4.2 + +::: details Legacy Fix (prior to 0.4.2) + +Due to an odd bug with ATI's TeraScale 2 GPUs, many users will experience erratic/strobing colours once finished installing accelerated patches and rebooting into macOS. The issue stems from an incorrect assumption in the GPU drivers where it will enforce the Billion Colour space on your display. To fix, simply force your Display into a lower color depth such as Million Colours. + +Applications that can set color depth are: + +* [SwitchResX](https://www.madrau.com) +* [ResXtreme](https://macdownload.informer.com/resxtreme/) + +::: + +## Cannot Login on 2011 15" and 17" MacBook Pros + +By default, OpenCore Legacy Patcher will assume MacBookPro8,2/3 have a faulty dGPU and disable acceleration. This is the safest option for most users as enabling dGPU acceleration on faulty Macs will result in failed booting. + +However, if your machine does not have the dGPU disabled via NVRAM, you'll experience a login loop. To work around this is quite simple: + +1. Boot macOS in Single User Mode + * Press Cmd+S in OpenCore's menu when you turn the Mac on +2. When the command line prompt appears, enter the dGPU disabler argument (at the bottom) +3. Reboot and patched macOS should work normally +4. If you still want to use the dGPU, run OpenCore Legacy Patcher and enable TS2 Acceleration from settings. Go to `Patcher Settings -> Developer Settings -> Set TeraScale 2 Accel`, then root patch again. +5. Either Reset NVRAM or set `gpu-power-prefs` to zeros to re-enable the dGPU + +```sh +# Forces GMUX to use iGPU only (ie. disable dGPU) +nvram FA4CE28D-B62F-4C99-9CC3-6815686E30F9:gpu-power-prefs=%01%00%00%00 +# To reset, simply write zeros or NVRAM Reset your Mac +nvram FA4CE28D-B62F-4C99-9CC3-6815686E30F9:gpu-power-prefs=%00%00%00%00 +``` + +## Black Boxes on HD3000 iGPUs + +A somewhat strange issue on Intel HD3000-based Macs, on 3rd party displays sometimes UI elements may become black and unreadable. To resolve, select either the generic `Display` or `Display P3` Color Profiles in Display Settings. + +* Mainly applicable for HDMI Displays, DVI and DisplayPort are generally unaffected. +* If you're inside Setup Assistant, press `Cmd` + `Option` + `Control` + `T` to launch Terminal. From there, run `open /System/Applications/System\ Preferences.app` +* Issue has spread to more Macs with macOS Ventura, including MacBook Airs and MacBook Pros + +| Default Color Profile | Display/Display P3 Profile | +| :--- | :--- | +| ![](./images/HD3000-Default-Colors.png) | ![](./images/HD3000-Display-Colors.png) | + +## Cannot Pair Bluetooth Devices + +In macOS Ventura, hover states may not function correctly which results in the "Connect" button not appearing in System Settings. To resolve: + +1. Enable Keyboard Navigation in System Settings -> Keyboard +2. Tab + space over Bluetooth devices in System Settings -> Bluetooth +3. Pair button should appear + +For more information, see [ASentientBot's post](https://forums.macrumors.com/threads/macos-13-ventura-on-unsupported-macs-thread.2346881/page-116?post=31858759#post-31858759). \ No newline at end of file diff --git a/docs/TROUBLESHOOT-MISC.md b/docs/TROUBLESHOOT-MISC.md new file mode 100644 index 000000000..497e23623 --- /dev/null +++ b/docs/TROUBLESHOOT-MISC.md @@ -0,0 +1,143 @@ +# Booting, installer and other issues + +**Booting** + +* [Stuck on `This version of Mac OS X is not supported on this platform` or (🚫) Prohibited Symbol](#stuck-on-this-version-of-mac-os-x-is-not-supported-on-this-platform-or-🚫-prohibited-symbol) +* [Cannot boot macOS without the USB](#cannot-boot-macos-without-the-usb) +* [Infinite Recovery OS Booting](#infinite-recovery-os-booting) +* [Stuck on boot after root patching](#stuck-on-boot-after-root-patching) +* [How to Boot Recovery through OpenCore Legacy Patcher](#how-to-boot-recovery-through-opencore-legacy-patcher) +* [Black Screen on MacBookPro11,3 in macOS Monterey](#black-screen-on-macbookpro11-3-in-macos-monterey) + +**Installer** + +* [Stuck on hard disk selection with greyed out buttons in installer](#stuck-on-hard-disk-selection-with-greyed-out-buttons-in-installer) +* [Installer fails with "an error occurred preparing the software update"](#installer-fails-with-an-error-occurred-preparing-the-software-update) +* [Stuck on "Less than a minute remaining..."](#stuck-on-less-than-a-minute-remaining) +* [Stuck on "Your Mac needs a firmware update"](#stuck-on-your-mac-needs-a-firmware-update) + +**Other** + +* [Reboot when entering Hibernation (`Sleep Wake Failure`)](#reboot-when-entering-hibernation-sleep-wake-failure) +* [Volume Hash Mismatch Error in macOS Monterey](#volume-hash-mismatch-error-in-macos-monterey) +* [Cannot Disable SIP in recoveryOS](#cannot-disable-sip-in-recoveryos) + + +## Stuck on `This version of Mac OS X is not supported on this platform` or (🚫) Prohibited Symbol + +This means macOS has detected an SMBIOS it does not support. To resolve this, ensure you're booting OpenCore **before** the macOS installer in the boot picker. Reminder that the option will be called `EFI Boot`. + +Once you've booted OpenCore at least once, your hardware should now auto-boot it until either an NVRAM reset occurs, or you remove the drive with OpenCore installed. + +However, if the 🚫 Symbol only appears after the boot process has already started (the bootscreen appears/verbose boot starts), it could mean that your USB drive has failed to pass macOS' integrity checks. To resolve this, create a new installer using a different USB drive (preferably of a different model.) + +## Cannot boot macOS without the USB + +By default, the OpenCore Patcher won't install OpenCore onto the internal drive itself during installs. + +After installing macOS, OpenCore Legacy Patcher should automatically prompt you to install OpenCore onto the internal drive. However, if it doesn't show the prompt, you'll need to either [manually transfer](https://dortania.github.io/OpenCore-Post-Install/universal/oc2hdd.html) OpenCore to the internal drive's EFI or Build and Install again and select your internal drive. + +Reminder that once this is done, you'll need to select OpenCore in the boot picker again for your hardware to remember this entry and auto boot from then on. + +## Infinite Recovery OS Booting + +With OpenCore Legacy Patcher, we rely on Apple Secure Boot to ensure OS updates work correctly and reliably with Big Sur. However this installs NVRAM variables that will confuse your Mac if not running with OpenCore. To resolve this, simply uninstall OpenCore and [reset NVRAM](https://support.apple.com/en-mide/HT201255). + +* Note: Machines with modified root volumes will also result in an infinite recovery loop until integrity is restored. + +## Stuck on boot after root patching + +**Applies to macOS Monterey and newer. Big Sur does not support snapshot reversion.** + +Boot into recovery by pressing space when your disk is selected on the OCLP bootpicker (if you have it hidden, hold ESC while starting up) + +* **Note:** If your disk name is something else than "Macintosh HD", make sure to change the path accordingly. You can figure out your disk name by typing `ls /Volumes`. + +Go into terminal and first mount the disk by typing +```sh +mount -uw "/Volumes/Macintosh HD" +``` +Then revert the snapshot +```sh +bless --mount "/Volumes/Macintosh HD" --bootefi --last-sealed-snapshot +``` +Now we're going to clean the /Library/Extensions folder from offending kexts while keeping needed ones. + +Run the following and **make sure to type it carefully** + +::: warning +If you have **FileVault 2 enabled**, you will need to mount the Data volume first. This can be done in Disk Utility by locating your macOS volume name, selecting its Data volume, and selecting the Mount option in the toolbar. +::: + +```sh +cd "/Volumes/Macintosh HD - Data/Library/Extensions" && ls | grep -v "HighPoint*\|SoftRAID*" | xargs rm -rf +``` + +Then restart and now your system should be restored to the unpatched snapshot and should be able to boot again. + +## How to Boot Recovery through OpenCore Legacy Patcher + +By default, the patcher will try to hide extra boot options such as recovery from the user. To make them appear, simply press the `Spacebar` key while inside OpenCore's Picker to list all boot options. + +## Black Screen on MacBookPro11,3 in macOS Monterey + +Due to Apple dropping NVIDIA Kepler support in macOS Monterey, [MacBookPro11,3's GMUX has difficulties switching back to the iGPU to display macOS correctly.](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/522) To work-around this issue, boot the MacBookPro11,3 in Safe Mode and once macOS is installed, run OCLP's Post Install Root Patches to enable GPU Acceleration for the NVIDIA dGPU. + +* Safe Mode can be started by holding `Shift` + `Enter` when selecting macOS Monterey in OCLP's Boot Menu. + +## Stuck on hard disk selection with greyed out buttons in installer + +Switch installer language to English. If the language selector doesn't show up, [reset NVRAM](https://support.apple.com/en-mide/102603) and boot into the installer again. + +You can switch back to different language once macOS has installed. + +## Installer fails with "an error occurred preparing the software update" + +This issue can be faced in the second phase of the installer with black background and Apple logo, cause of this issue is unknown. To possibly resolve this issue, keep rebooting into 'macOS Installer' (the second phase) multiple times until it ultimately goes through. + +## Stuck on "Less than a minute remaining..." + +A common area for systems to get "stuck", namely for units that are missing the `AES` CPU instruction/older mobile hardware. During this stage, a lot of heavy cryptography is performed, which can make systems appear to be stuck. In reality they are working quite hard to finish up the installation. + +Because this step can take a few hours or more depending on drive speeds, be patient at this stage and do not manually power off or reboot your machine as this will break the installation and require you to reinstall. If you think your system has stalled, press the Caps Lock key. If the light turns on, your system is busy and not actually frozen. + +## Stuck on "Your Mac needs a firmware update" + +Full error: "Your Mac needs a firmware update in order to install to this Volume. Please select a Mac OS Extended (Journaled) volume instead." + +This error occurs when macOS determines that the current firmware does not have full APFS support. To resolve this, when installing OpenCore, head to "Patcher Settings" and enable "Moderate SMBIOS Patching" or higher. This will ensure that the firmware reported will show support for full APFS capabilities. + + +## Reboot when entering Hibernation (`Sleep Wake Failure`) + +[Known issue on some models](https://github.com/dortania/Opencore-Legacy-Patcher/issues/72), a temporary fix is to disable Hibernation by executing the following command in the terminal: + +``` +sudo pmset -a hibernatemode 0 +``` + +## Volume Hash Mismatch Error in macOS Monterey + +A semi-common popup some users face is the "Volume Hash Mismatch" error: + +

+ +

+ +What this error signifies is that the OS detects that the boot volume's hash does not match what the OS is expecting, this error is generally cosmetic and can be ignored. However if your system starts to crash spontaneously shortly after, you'll want to reinstall macOS fresh without importing any data at first. + +* Note that this bug affects native Macs as well and is not due to issues with unsupported Macs: [OSX Daily: “Volume Hash Mismatch” Error in MacOS Monterey](https://osxdaily.com/2021/11/10/volume-hash-mismatch-error-in-macos-monterey/) + +Additionally, it can help to disable FeatureUnlock in Settings -> Misc Settings as this tool can be strenuous on systems with weaker memory stability. + + +## Cannot Disable SIP in recoveryOS + +With OCLP, the patcher will always overwrite the current SIP value on boot to ensure that users don't brick an installation after an NVRAM reset. However, for users wanting to disable SIP entirely, this can be done easily. + +Head into the GUI, go to Patcher Settings, and toggle the bits you need disabled from SIP: + +| SIP Enabled | SIP Lowered (Root Patching) | SIP Disabled | +| :--- | :--- | :--- | +| ![](./images/OCLP-GUI-Settings-SIP-Enabled.png) | ![](./images/OCLP-GUI-Settings-SIP-Root-Patch.png) | ![](./images/OCLP-GUI-Settings-SIP-Disabled.png) | + diff --git a/docs/TROUBLESHOOT-NONMETAL.md b/docs/TROUBLESHOOT-NONMETAL.md new file mode 100644 index 000000000..ee6cc4425 --- /dev/null +++ b/docs/TROUBLESHOOT-NONMETAL.md @@ -0,0 +1,114 @@ +# Non-Metal issues + +The below page is for users experiencing issues with their overall usage of macOS Big Sur and newer and the Legacy Graphics Acceleration patches. Note that the following GPUs currently do not have acceleration support in Big Sur and newer: + +* Intel 3rd and 4th Gen - GMA series + +For those unfamiliar with what is considered a non-Metal GPU, see the chart below: + +::: details macOS GPU Chart + +Metal is Apple's in-house graphics API that acts as a replacement for OpenGL/OpenCL, introduced in 2015. With the release of macOS Mojave, every system without a Metal-capable GPU was dropped. + +| Graphics Vendor | Architecture | Series | Supports Metal | +| :--- | :--- | :--- | :--- | +| ATI | TeraScale 1 | HD 2XXX - HD 4XXX | No | +| ^^ | TeraScale 2 | HD 5XXX - HD 6XXX | ^^ | +| AMD | GCN (and newer) | HD 7XXX+ | Yes | +| NVIDIA | Tesla | 8XXX - 3XX | No | +| ^^ | Fermi | 4XX - 5XX | ^^ | +| ^^ | Kepler | 6XX - 7XX | Yes | +| ^^ | Maxwell | 8XX - 9XX | No (on 10.14 and newer) | +| ^^ | Pascal | 10XX | ^^ | +| Intel | GMA | GMA 900 - GMA X3000 | No | +| ^^ | Iron Lake | HD series | ^^ | +| ^^ | Sandy Bridge | HD 3000 | ^^ | +| ^^ | Ivy Bridge (and newer) | HD 4000 | Yes | + +::: + +* [Broken Background Blurs](#broken-background-blurs) +* [Downloading older non-Metal Apps](#downloading-older-non-metal-apps) +* [Unable to run Zoom](#unable-to-run-zoom) +* [Unable to grant special permissions to apps (ie. Camera Access to Zoom)](#unable-to-grant-special-permissions-to-apps-ie-camera-access-to-zoom) +* [Photos and Maps app issues](#photos-and-maps-app-issues) +* [Cannot press "Done" when editing a Sidebar Widget](#cannot-press-done-when-editing-a-sidebar-widget) +* [Unable to allow Safari Extensions](#unable-to-allow-safari-extensions) + +## Broken Background Blurs + +By default with the non-Metal acceleration patches, many background blur menus may act distorted when moving a cursor over it. With 0.4.1 and newer, users can enable a new Beta Blur feature to try and resolve the issue: + +![]() + +
+ Beta Blur settings +
+ +Do note that enabling beta blurs can be more demanding on slower hardware +## Downloading older non-Metal Apps + +Many Apple apps now have direct reliance on Metal for proper functioning, however legacy builds of these apps still do work in Big Sur. See below for archive of many apps such as Pages, iMovie, GarageBand. + +* [Apple Apps for Non-Metal Macs](https://archive.org/details/apple-apps-for-non-metal-macs) + +Note: This archive assumes that you own these copies of these apps through the Mac App Store, Dortania does not condone piracy + +## Unable to run Zoom + +Currently Zoom relies partially on Metal and so needs a small binary patch. Dosdude1 has provided a nice script for this: + +* [Zoom Non-Metal Fix](http://dosdude1.com/catalina/zoomnonmetal-new.command.zip) + +## Unable to grant special permissions to apps (ie. Camera Access to Zoom) +Currently for Ventura 13.3 and newer, due to new patches required, permissions are yet again broken. Use TCCPlus in the Workaround dropdown to work around the issue. + +This issue is fully resolved for 13.2.1 and lower starting from 0.2.5. + +::: details Workaround for 0.2.4, Ventura 13.3+ + +Due to the usage of amfi_get_out_of_my_way=1, macOS will fail to prompt users for special permissions upon application start as well as omit the entries in System Preferences. To work around this, we recommend users install tccplus to manage permissions. + +[Download TCCPlus](https://github.com/jslegendre/tccplus) + +Example usage with Discord and microphone permissions: + +```sh +# Open Terminal and run the following commands +cd ~/Downloads/ +chmod +x tccplus +./tccplus add Microphone com.hnc.Discord +``` + +For those who may experience issues with `tccplus`, you can manually patch `com.apple.TCC` to add permissions: + +```sh +# get app id (Zoom.us used in example): +$ osascript -e 'id of app "zoom.us"' +# output: us.zoom.xos + +$ sudo sqlite3 ~/Library/Application\ Support/com.apple.TCC/TCC.db "INSERT or REPLACE INTO access VALUES('kTCCServiceMicrophone','us.zoom.xos',0,2,0,1,NULL,NULL,NULL,'UNUSED',NULL,0,1541440109);" + +$ sudo sqlite3 ~/Library/Application\ Support/com.apple.TCC/TCC.db "INSERT or REPLACE INTO access VALUES('kTCCServiceCamera','us.zoom.xos',0,2,0,1,NULL,NULL,NULL,'UNUSED',NULL,0,1541440109);" +``` + +::: + +## Photos and Maps app issues + +**Starting from macOS Monterey, Maps and everything relying on it (such as Find My or 'Places' in Photos) are non-functional on non-Metal due to Metal reliance.** + + +## Cannot press "Done" when editing a Sidebar Widget + +Workaround: Press some combination of Tab, or Tab and then Shift-Tab, or just Shift-Tab until the "Done" button is highlighted. Then press spacebar to activate the button, the same as in any other dialog with a highlighted button halo. + + +## Unable to allow Safari Extensions + +Due to a bug in the legacy acceleration patches, users won't be able to enable Safari Extensions. + +The following tool can be used to work-around this issue: + +* [Non-Metal Safari Extensions](https://github.com/moosethegoose2213/Non-Metal-Safari-Extensions/) +