diff --git a/docs/ACCEL.md b/docs/ACCEL.md index ce64b1005..243e121d1 100644 --- a/docs/ACCEL.md +++ b/docs/ACCEL.md @@ -1,4 +1,4 @@ -# Working Around Non-Metal Issues +# Non-Metal Issues * [Broken Background Blurs](#broken-background-blurs) * [Downloading older non-Metal Apps](#downloading-older-non-metal-apps) diff --git a/docs/APPTROUBLESHOOT.md b/docs/APPTROUBLESHOOT.md new file mode 100644 index 000000000..3ac02d9d1 --- /dev/null +++ b/docs/APPTROUBLESHOOT.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/FAQ.md b/docs/FAQ.md index 6b63de60d..29401b718 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,6 +1,5 @@ # FAQ - * [Application requirements](#application-requirements) * [Application versioning](#application-versioning) * [How do I make sure I'm all up to date?](#how-do-i-make-sure-i-m-all-up-to-date) @@ -75,7 +74,7 @@ General updates are usually fine, though it is always a good idea to wait few da It is extremely recommended to disable automatic updates (even downloading) when using OCLP, as Apple has recently changed the way automatic updates work. Updates are now getting staged during the download process and are already modifying the system volume, which can lead to broken system out of nowhere since the operating system gets into a liminal state between two versions. You can still manually initiate an update when you're ready to do so. -For a related "System version mismatch" error while root patching and more information, refer to [System version mismatch error when root patching](https://dortania.github.io/OpenCore-Legacy-Patcher/TROUBLESHOOTING.html#system-version-mismatch-error-when-root-patching) for troubleshooting. +For a related "System version mismatch" error while root patching and more information, refer to [System version mismatch error when root patching](https://dortania.github.io/OpenCore-Legacy-Patcher/APPTROUBLESHOOT.html#system-version-mismatch-error-when-root-patching) for troubleshooting. * 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. @@ -109,11 +108,11 @@ macOS doesn't allow direct downgrades, as such you will have to wipe the disk in **Lacking or broken root patches** -If your system is being **really** slow and macOS is lacking wallpaper and transparency in Dock and menubar, make sure to install root patches to get proper drivers and functionality. Refer to [Applying post install volume patches](https://dortania.github.io/OpenCore-Legacy-Patcher/POST-INSTALL.html#applying-post-install-volume-patches) and the [Troubleshooting](https://dortania.github.io/OpenCore-Legacy-Patcher/TROUBLESHOOTING.html) section for more information. +If your system is being **really** slow and macOS is lacking wallpaper and transparency in Dock and menubar, make sure to install root patches to get proper drivers and functionality. Refer to [Applying post install volume patches](https://dortania.github.io/OpenCore-Legacy-Patcher/POST-INSTALL.html#applying-post-install-volume-patches) section for more information. **Root patches will be wiped by macOS updates and have to be reinstalled after an update finishes.** -Patches can also break if automatic updates are enabled and an update prematurely modifies the system volume, refer to [System version mismatch error when root patching](https://dortania.github.io/OpenCore-Legacy-Patcher/TROUBLESHOOTING.html#system-version-mismatch-error-when-root-patching) for more information. +Patches can also break if automatic updates are enabled and an update prematurely modifies the system volume, refer to [System version mismatch error when root patching](https://dortania.github.io/OpenCore-Legacy-Patcher/APPTROUBLESHOOT.html#system-version-mismatch-error-when-root-patching) for more information. **Spotlight** @@ -167,7 +166,7 @@ Everything older than mentioned are Non-Metal and therefore only support OpenGL. ::: -Refer to [Supported models,](https://dortania.github.io/OpenCore-Legacy-Patcher/MODELS.html) the [Non-Metal GitHub issue](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108) and [Working Around Non-Metal Issues](https://dortania.github.io/OpenCore-Legacy-Patcher/ACCEL.html) pages for more information. +Refer to [Supported models,](https://dortania.github.io/OpenCore-Legacy-Patcher/MODELS.html) the [Non-Metal GitHub issue](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108) and [Non-Metal Issues](https://dortania.github.io/OpenCore-Legacy-Patcher/ACCEL.html) pages for more information. ## What are FeatureUnlock and mediaanalysisd? diff --git a/docs/POST-INSTALL.md b/docs/POST-INSTALL.md index d904c96a9..f11503a1c 100644 --- a/docs/POST-INSTALL.md +++ b/docs/POST-INSTALL.md @@ -17,7 +17,7 @@ Once you've installed macOS through OpenCore, you can boot up and go through the And voila! No more USB drive required. -If you're having issues with undetected internal disk, refer to [Internal disk missing when building OpenCore](https://dortania.github.io/OpenCore-Legacy-Patcher/TROUBLESHOOTING.html#internal-disk-missing-when-building-opencore) for troubleshooting. +If you're having issues with undetected internal disk, refer to [Internal disk missing when building OpenCore](https://dortania.github.io/OpenCore-Legacy-Patcher/APPTROUBLESHOOT.html#internal-disk-missing-when-building-opencore) for troubleshooting. ## Booting seamlessly without Boot Picker diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index daa5e4543..6069b4e0d 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -1,17 +1,10 @@ -# General troubleshooting +# Booting, hardware and other issues -Here are some common errors that users may experience while using this patcher: - -* [OpenCore Legacy Patcher not launching](#opencore-legacy-patcher-not-launching) -* ["You don't have permission to save..." error when creating USB installer](#you-don-t-have-permission-to-save-error-when-creating-usb-installer) * [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) * [Stuck on hard disk selection with greyed out buttons in installer](#stuck-on-hard-disk-selection-with-greyed-out-buttons-in-installer) * [Cannot boot macOS without the USB](#cannot-boot-macos-without-the-usb) * [Infinite Recovery OS Booting](#infinite-recovery-os-booting) -* [Internal disk missing when building OpenCore](#internal-disk-missing-when-building-opencore) -* [System version mismatch error when root patching](#system-version-mismatch-error-when-root-patching) * [Stuck on boot after root patching](#stuck-on-boot-after-root-patching) -* ["Unable to resolve dependencies, error code 71" when root patching](#unable-to-resolve-dependencies-error-code-71-when-root-patching) * [Reboot when entering Hibernation (`Sleep Wake Failure`)](#reboot-when-entering-hibernation-sleep-wake-failure) * [Installer fails with "an error occurred preparing the software update"](#installer-fails-with-an-error-occurred-preparing-the-software-update) * [How to Boot Recovery through OpenCore Legacy Patcher](#how-to-boot-recovery-through-opencore-legacy-patcher) @@ -30,37 +23,6 @@ Here are some common errors that users may experience while using this patcher: * [No T1 functionality after installing Sonoma or newer](#no-t1-functionality-after-installing-sonoma-or-newer) -## 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 -``` - -## "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. - - ## 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`. @@ -89,58 +51,6 @@ With OpenCore Legacy Patcher, we rely on Apple Secure Boot to ensure OS updates * Note: Machines with modified root volumes will also result in an infinite recovery loop until integrity is restored. -## 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 -
- - -## 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". - -::: ## Stuck on boot after root patching @@ -172,30 +82,6 @@ cd "/Volumes/Macintosh HD - Data/Library/Extensions" && ls | grep -v "HighPoint* Then restart and now your system should be restored to the unpatched snapshot and should be able to boot again. -## "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. ## Reboot when entering Hibernation (`Sleep Wake Failure`)