Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/lzhoang2801/OpCore-Simplify/llms.txt

Use this file to discover all available pages before exploring further.

This page covers the most common problems encountered while using OpCore Simplify to generate an EFI, during the macOS installation process, and after a successful install. Each section is collapsed for readability — click a heading to expand it. If your issue is not covered here, check the GitHub Issues tracker or the Dortania OpenCore Install Guide for deeper guidance.
OpCore Simplify significantly reduces EFI setup time, but a working Hackintosh still requires understanding basic concepts from the Dortania OpenCore Install Guide. The tool does not guarantee a successful first-attempt installation. Patience and methodical troubleshooting are part of the process.

​
Hardware Report Issues

The tool requires a hardware report to be loaded before any other option in the main menu becomes available. If you attempt to access ACPI patches, kexts, macOS version selection, or the build option without loading a report first, the tool will display an error and return to the menu.Solution: Select E. Export hardware report on Windows to generate and immediately load a fresh Report.json, or select S. Select hardware report and navigate to an existing Report.json file generated by Hardware Sniffer. See Hardware Report for the full workflow.
After loading a report, the tool validates its structure. If required fields are absent or device IDs are malformed (e.g., not a valid 8-character hex string), validation fails with an error message identifying the problematic field.Solution: Re-export the hardware report using the latest version of Hardware Sniffer. Outdated versions of Hardware Sniffer may produce reports in an older schema that the current tool version does not accept. Delete any old Report.json files and regenerate from scratch.
The compatibility checker halts and prints No GPU found! if the GPU section is missing from the loaded report.Possible causes and solutions:
  • The GPU was disabled in Device Manager (Windows) or not detected at the time of export. Enable or re-seat the GPU, reboot, and re-export.
  • Integrated graphics may have been disabled in BIOS in favour of a discrete GPU. If both are present and you want iGPU headless mode, ensure both appear in Device Manager before exporting.
  • On AMD APU systems, the iGPU must not be disabled in BIOS. Re-enable it and re-export.
Patches such as BATP, PLUG, GPI0, and PRW require a live DSDT/ACPI dump from the target machine. If the tool detects that these patches are needed but no ACPI dump folder was provided, it will prompt you to specify the path to the ACPI dump directory.Solution: Re-export the hardware report with Hardware Sniffer and ensure the Dump ACPI tables option is enabled during export. The resulting ACPI dump folder will be placed alongside Report.json. If you already have the dump but the tool cannot find it, use the manual path prompt to point to the correct directory.

​
Build Failures

OpCore Simplify downloads OpenCorePkg and all required kexts from Dortania Builds and GitHub releases before each build. A network error at this stage aborts the download.Solution:
  1. Check your internet connection and try again.
  2. If you are behind a corporate proxy or firewall, ensure that github.com, dortania.github.io, and nightly.link are reachable.
  3. The tool will prompt you to retry the download — select Y to try again without restarting the whole build process.
  4. If a specific kext URL consistently fails, check the GitHub Issues tracker — the URL may have changed upstream.
The tool creates an OCK_Files/ directory in the OpCore Simplify folder to cache downloaded bootloader and kext archives between builds. If this directory cannot be created, the build will fail.Solution:
  • On Windows, try running OpCore-Simplify.bat as Administrator (right-click → Run as administrator).
  • On macOS or Linux, ensure the current user has write permission to the OpCore Simplify directory: chmod -R u+w /path/to/OpCore-Simplify.
  • If the directory exists but is corrupted, delete OCK_Files/ manually and restart the build to force a fresh download.
macserial is used during the build to generate SMBIOS serial numbers, MLB values, and UUIDs. If it is missing or has lost its execute permission, SMBIOS generation fails.Solution: Delete the entire OCK_Files/ directory and run the build again. The tool will re-download and extract macserial along with the rest of the OpenCorePkg archive. On macOS/Linux, also run chmod +x OCK_Files/macserial if the issue persists after re-downloading.

​
Boot Issues

If your system boots directly into Windows or shows no OS at all, OpenCore is not being loaded.Solution:
  1. Enter your BIOS/UEFI firmware setup and check the Boot Order. Move the entry named OPENCORE (or the EFI partition of your USB) to the top.
  2. Ensure Secure Boot is disabled. OpenCore’s default configuration does not include Secure Boot keys.
  3. Verify that the EFI folder is placed on a FAT32-formatted partition at the root (/EFI/OC/).
  4. On some boards, you may need to add a manual UEFI boot entry pointing to \EFI\OC\OpenCore.efi.
This message means macOS can find the kernel but cannot locate the disk it is supposed to boot from. This is almost always a USB mapping or storage issue.Solution:
  1. USB mapping is incomplete. UTBDefault enables all ports but some systems have more than 15 USB ports, which macOS rejects. If the USB drive containing the installer is on a port that exceeds the limit, macOS cannot read it. Try a different USB port (prefer USB 2.0 ports or rear-panel ports during install).
  2. Intel VMD is enabled. If your NVMe SSD is behind an Intel VMD controller, macOS cannot see it. Disable Intel VMD in BIOS.
  3. SATA controller not detected. Add CtlnaAHCIPort.kext manually if your SATA controller is not natively supported.
A black screen after the progress bar completes indicates the GPU failed to initialise display output.Checklist:
  1. Add the -v verbose boot argument to reveal whether the boot actually completes or panics silently.
  2. Verify kext selection: Intel iGPU systems need WhateverGreen; AMD Ryzen APU systems need NootedRed; RDNA 2 discrete AMD GPUs need NootRX. Only one GPU kext can be active. Re-run the build and confirm the correct kext is selected.
  3. NVIDIA: Pascal and Maxwell are limited to High Sierra natively. On newer macOS, no display output is expected without OCLP web driver support (which is not available for Pascal/Maxwell on modern macOS).
  4. AMD legacy GPU: If you applied OCLP root patches, remove -radvesa or -amd_no_dgpu_accel from boot arguments — these flags force VESA mode and prevent GPU acceleration.
  5. Try a different display output. Some framebuffer patches conflict with specific connector types. Try HDMI instead of DisplayPort or vice versa.

​
macOS Installation Issues

A crash or freeze during installation is usually caused by a kext incompatibility with the chosen macOS version, or a missing patch for your hardware.Solution:
  1. Add -v to your boot arguments to enable verbose mode. The last line printed before the crash or freeze usually identifies the offending kext or subsystem.
  2. Check that the kexts selected for your hardware are compatible with the target macOS version. For example, AsusSMC is not compatible with macOS Sonoma and newer — the tool handles this, but manually adding incompatible kexts will cause crashes.
  3. If the crash happens early (before the installer GUI loads), revisit the BIOS checklist: Secure Boot disabled, Above 4G Decoding enabled, CSM/Legacy Boot disabled.
  4. If the crash happens late (during the “About 2 minutes remaining” phase), it is often a USB power issue — try a different USB port or hub.
iServices require macOS to believe it is running on a genuine Mac with valid, unused serial numbers and a correctly configured network stack.Requirements checklist:
  • Valid SMBIOS: The serial number, MLB, and ROM generated by OpCore Simplify must not already be in use by a real Mac. Generate a new set if iServices fail after the first attempt.
  • USB mapping: A proper USB port map (replacing UTBDefault with a custom UTBMap.kext) is required — see USB Mapping.
  • Real or emulated Ethernet MAC: The en0 network interface must have a stable, non-random MAC address. OpCore Simplify injects the built-in property on Ethernet devices for this purpose. If you have no physical Ethernet, use the NullEthernet kext and RMNE ACPI patch combination.
  • Sign out and back in: After fixing SMBIOS and USB mapping, sign out of your Apple ID in System Settings and sign back in. iMessage may require waiting 24 hours or contacting Apple Support to unlock the account.
Wi-Fi appearing in System Settings but failing to connect, or Wi-Fi not appearing at all, each have different causes.itlwm (Intel Wi-Fi): itlwm spoofs as an Ethernet adapter and does not appear in the Wi-Fi menu. You need to install the HeliPort companion app to manage connections. OpCore Simplify can optionally inject a Wi-Fi profile (WiFi-Profile.xml) so itlwm connects automatically at boot.AirportItlwm (Intel Wi-Fi): AirportItlwm requires a different binary for each major macOS version. If you updated macOS, the kext may no longer match. Re-run OpCore Simplify targeting the new macOS version and rebuild the EFI.Broadcom Wi-Fi on Ventura/Sonoma: Non-native Broadcom cards are dropped in Ventura and Sonoma. Re-enable them by running OpenCore Legacy Patcher root patches after installation.

​
Post-Install Issues

Immediate wake after sleep is almost always caused by a USB device or a bad _PRW ACPI return value. True sleep failure (system won’t enter sleep) can also be USB-related or caused by an incomplete EC definition.Solution:
  1. Instant wake: The PRW ACPI patch (GPRW/UPRW fix) should handle this for most systems. If it was not applied, re-run the tool with the correct ACPI dump and rebuild.
  2. USB wake: Disconnect all USB devices (especially hubs, keyboards with USB passthrough) and test sleep. If sleep works without USB peripherals, you need proper USB mapping — create a custom UTBMap.kext via USB Mapping.
  3. EC (Embedded Controller): On desktops, the FakeEC ACPI patch provides the EC definition macOS requires for sleep. Verify it was applied.
  4. Check Console.app (filter for Wake reason) to identify which device is triggering the wake event.
If you used OpenCore Legacy Patcher to extend support for an older GPU (Kepler NVIDIA, legacy AMD GCN, legacy Broadcom Wi-Fi), the root patches must be applied inside macOS after each major update.Solution:
  1. Open OpenCore Legacy Patcher.
  2. Select Post-Install Root Patch.
  3. Apply the patches and reboot.
  4. If you have an AMD GPU, remove -radvesa or -amd_no_dgpu_accel from your boot arguments in config.plist after patching — these flags force software rendering and must be removed for hardware acceleration to work.
See OpenCore Legacy Patcher for the full post-install patching walkthrough.
AppleALC requires the correct layout ID for your audio codec to function. An incorrect layout ID either produces no audio or causes AppleALC to fail silently.Solution:
  1. Re-run OpCore Simplify. During the build, the tool will prompt you to select a layout ID from a list of IDs known to work with your detected audio codec. Try a different layout ID from the list.
  2. Verify that the alcid=XX boot argument (or equivalent DeviceProperties entry) is set to the same layout ID.
  3. Check that AppleALC.kext and Lilu.kext are present in EFI/OC/Kexts/ and enabled in config.plist.
  4. If your codec is not in the AppleALC supported list, it cannot be patched without writing a new AppleALC layout — see the AppleALC wiki.
Battery status requires the BATP ACPI patch, which modifies EC (Embedded Controller) field definitions in the DSDT to use 8-bit-wide fields that macOS can read. It also requires the ECEnabler kext for fields longer than 1 byte.Solution:
  1. Verify that the BATP patch was applied. It requires an ACPI dump — if no dump was provided during report export, the patch cannot be generated. Re-export with Hardware Sniffer (ACPI dump enabled) and rebuild the EFI.
  2. Confirm that ECEnabler.kext is present and enabled in config.plist. Without it, EC fields over 1 byte in length cannot be read and battery percentage will not display.
  3. Some laptops require additional DSDT patches beyond what BATP generates. If the percentage still does not appear, consult the Dortania Fixing Battery Status guide.

​
Self-Update Issues

At launch, OpCore Simplify queries the GitHub API to check whether a newer version is available. If this request fails, the tool prints Could not verify the latest version from GitHub. and prompts: Do you want to skip the update process? (yes/No):Solution:
  • Type yes to skip the update check entirely and continue with the currently installed version.
  • Type no to force the tool to proceed with an update anyway (the update runs using a forced marker rather than a real version comparison). Use this if you know an update is available but the GitHub API is temporarily unreachable.
  • If the error persists, verify that api.github.com is reachable from your machine. Corporate firewalls and DNS-level blockers sometimes intercept GitHub API requests.
If the self-update process is interrupted (power loss, killed process, network drop), the tool’s Python files may be partially overwritten.Solution:
  1. Download the latest ZIP manually from https://github.com/lzhoang2801/OpCore-Simplify/archive/refs/heads/main.zip.
  2. Extract the ZIP and copy all files from the extracted folder into your existing OpCore Simplify directory, overwriting everything.
  3. Do not delete OCK_Files/ unless you also want to re-download OpenCorePkg and kext archives — those are independent of the tool’s own Python scripts.

​
External Resources

If the solutions on this page do not resolve your issue, the following resources provide deeper reference material:

Build docs developers (and LLMs) love

Get started for freeTalk to us