How to Fix USB Ports on macOS Tahoe
This guide describes how to fix USB Ports on macOS Tahoe (26.0) and later. By following this guide, you'll be able to fix USB ports on systems you intent to use macOS Tahoe and can still have the functional ports on macOS Sequoia or prior.Overview
Recently, Apple announced macOS Tahoe (26.0) on June 9, WWDC25 which is one of the most awaited release in 2025. As always, if you're an Apple user, you might be familiar with how Apple loves to make changes in their new releases and is consistent throughout every year. While not expected, Apple has made changes to its USB stack in macOS Tahoe 26 and as a result, the USB ports are broken on macOS Tahoe. This is because, macOS Tahoe uses a new key for the identification of the USB ports which also reflects in the IOReg and System Report>USB. Due to the USB ports not functional, the installer halts and gives the famous "still waiting for device" error when booting via the USB installer. Luckily, you don't have to start from scratch and map your USB ports again as you'll just have to adapt these new key for the identification of the USB ports, while retaining the existing mapped kext.To simplify, here are the old and new key for the ports identification:
Old:
UsbConnector, portNew:
usb-port-type, usb-port-numberIf its still not clear to you, let's understand in a more simple way. The
UsbConnector is replaced by usb-port-type key and the port is replaced by usb-port-number. Where, UsbConnector refers to connector type and port refers to port number. Similarly, the usb-port-type refers to the connector type and usb-port-number refers to port number which is already understood.Users who have mapped the USB Ports via native ACPI method, shouldn't require this guide as these keys are already defined via UPC which functions normally on macOS Tahoe and prior
.
Support
This guide supports USBPorts.kext generated by Hackintool and USBMap.kext generated by @Corpnewt USBMap tool.Requirements
Before this guide can work for you, you'll need to have your USB ports mapped on macOS Sequoia or prior before following this guide. See Mapping USB Ports for more information.Fixing USB Ports on macOS Tahoe
To fix the USB Ports without having the need to map it again, there are two available methods. Depending on your choice, choose one of the method from below:Method #1: Automatic
To fix the USB Ports using the automatic method, follow the steps below:1. Make a backup of the original USBPorts.kext or USBMap.kext or copy it to elsewhere.
2. Open the Terminal and execute the following commands. When prompted, enter your password.
Bash:
#Install Command Line Tools for Xcode
xcode-select --install
#Clone USBMap Tool
git clone https://github.com/corpnewt/USBMap
#Move to the directory
cd USBMap
#Modify permission
chmod +x USBMapInjectorEdit.command
#Run USBMapInjector Tool
./USBMapInjectorEdit.command3. Drag the USBPorts.kext or USBMap.kext to Terminal window and press enter key. You can either simply drag the USBPorts.kext or the Info.plist. The current IOKitPersonalities will be displayed on top.
4. Press
U and then enter key to update keys for macOS Tahoe.5. Press
C and then enter key to set Classes to AppleUSBHostMergeProperties.6. You can change the SMBIOS target using
S. This is required if your existing SMBIOS does not supports macOS Tahoe. Please note that you'll also have to change the SMBIOS in the config.plist as well.The changes will be reflected on top.
7. Press
Q to quit USBMapInjectorEdit.8. Quit Terminal.
Method #2: Manual
To fix the USB Ports using the manual method, follow the steps below:1. Navigate to ESP/EFI/OC/Kexts directory.
2. Make a backup of the existing USBPorts.kext or USBMap.kext.
3. Right click on USBPorts.kext or USBMap.kext and select Show Package Contents:
4. Open Info.plist using Xcode or any Plist editor from the Contents directory.
5. Replace
com.apple.driver.AppleUSBMergeNub with com.apple.driver.AppleUSBHostMergeProperties in CFBundleIdentifier and AppleUSBMergeNub with AppleUSBHostMergeProperties in IOClass.6. Locate
IOKitPersonalities and expand ports under IOProvideMergeProperties. You should have something like following:
7. Create two New Child with the name
usb-port number and usb-port-type in each of the ports (HSXX and SSXX) defined in the mapped kext and set the Class (value type) as Data for usb-port-number and Number for usb-port-type.
8. Match the value with that of the existing configuration i.e.
UsbConnector with usb-port-type and port with usb-port-number as explained above. For example, the HS03 has UsbConnector set as 3 (USB 3.0) and port as 03000000 respectively. Similarly, change the values to the new key to match yours.
You can also consider re-arranging the keys for better visual and to avoid any possible confusion.
9. Review the changes and ensure that the Class type and Values defined are appropriate. Once you have made the required changes, it should look something like below:
Here's how it looks Before and After:
10. Save changes to the
Info.plist.11. Reset NVRAM and boot macOS Tahoe installer.
NOTE: There is no need to delete existing keys (
UsbConnector and port). By keeping both the keys, you can use the same mapped kext and can boot macOS Tahoe or prior without having the need to make a separate kext for prior macOS versions.That's all folks!
Last edited:
