docs/TROUBLESHOOT-HARDWARE.md
For those unfamiliar with what is considered a non-Metal GPU, see the chart in FAQ
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:
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.
In macOS, GPU drivers are often dropped from the OS with each major release of it. If you're using OCLP v0.4.4 or newer, 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.
See Applying Post Install Volume Patches for more information.
If you swapped a GPU from stock to a Metal GPU in a Mac Pro after installing OS, see No acceleration after a Metal GPU swap on Mac Pro for instructions.
Check the list below to see what GPUs require patching in which OS versions.
:::details GPUs requiring patching in different macOS versions
AMD Navi (RX 5000 - 6000 series) GPUs are non-functional in Mac Pro 2008 to 2012 using Ventura and newer due to lack of AVX2 support.
Sequoia
Sonoma
Ventura
Monterey
Big Sur
:::
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.
<div align="left"> </div>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.
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.
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:
Build tab.MacPro3,1/Xserve2,1 Workaround.Dual CPUs cannot be enabled in any circumstance if Sequoia or newer is installed, even in multiboot scenarios. Doing so will make Sequoia unbootable.
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 for most configurations after reversion. Reason why this happens is automatic root patching during USB install and the autopatcher assuming you will be using the original graphics card and therefore doing non-Metal patching. Metal and non-Metal GPUs cannot be used at the same time as Non-Metal patching completely bypasses Metal and requires removing some parts such as drivers for other cards, which causes Metal cards to not accelerate after swapping.
Alternatively, you can remove "AutoPkg-Assets.pkg" from /Library/Packages on the USB drive before proceeding with the installation. This package includes the assets for root patching and the system won't be autopatched if they aren't present. To see the folder, enable hidden files with Command + Shift + .
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.
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 |
::: 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 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:
ssh username@lan-ip-address - Connects via SSH, change username and IP address to the system's/Applications/OpenCore-Patcher.app/Contents/MacOS/OpenCore-Patcher --patch_sys_vol - Installs root patches via CLIsudo reboot.More information can be found here:
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.
<div align="left"> </div>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 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 forcing the color output of their monitor from Billions to Millions of colors helped greatly. Apps easily allowing this customization are SwitchResX, ResXreme and EasyRes.
:::
Fixed for macOS Ventura starting from 0.6.6. Big Sur and Monterey will continue to exhibit the issue.
This issue affects TeraScale 1 GPUs (ie. ATI/AMD Radeon HD2000-4000). 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.
In the event Apple removes 11.2.3 from their catalogue, we've provided a mirror below:
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:
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 can work around this limitation, however, note that you'll need to use older drivers (5.2.6):
Note: This driver only provides partial support in macOS, full graphics acceleration is not currently available on displays driven by DisplayLink.
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:
:::
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:
Settings -> Root Patching -> TeraScale 2 Acceleration, then root patch again.gpu-power-prefs to zeros to re-enable the dGPU# 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
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.
Cmd + Option + Control + T to launch Terminal. From there, run open /System/Applications/System\ Preferences.app| Default Color Profile | Display/Display P3 Profile |
|---|---|
In macOS Ventura, hover states may not function correctly which results in the "Connect" button not appearing in System Settings. To resolve:
For more information, see ASentientBot's post.