• Become a Premium Member for $25/year with no ads to improve your community experience. Upgrade to Pro Account for faster response and no wait times!

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, port
New: usb-port-type, usb-port-number

If 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.command

3. 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:
Screen Shot 2025-06-18 at 3.11.04 PM-min.png

4. Open Info.plist using Xcode or any Plist editor from the Contents directory.

Screen Shot 2025-06-18 at 3.11.40 PM-min.png
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:

Screen Shot 2025-06-18 at 2.53.09 AM-min.png Screen Shot 2025-06-18 at 3.15.24 PM-min.png
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.
Screen Shot 2025-06-18 at 2.59.20 AM-min.png
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.
Screen Shot 2025-06-18 at 2.59.54 AM-min.png
You can also consider re-arranging the keys for better visual and to avoid any possible confusion.

Screen Shot 2025-06-18 at 3.25.36 PM-min.png
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:

Screen Shot 2025-06-18 at 4.02.15 PM-min.png
Here's how it looks Before and After:
Screen Shot 2025-06-18 at 4.03.47 PM-min.png Screen Shot 2025-06-18 at 4.02.15 PM-min.png


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:
Thanks a lot, very detailed guide as always; will definitely be useful for me when Tahoe is out of Beta !
 
Thanks a lot, very detailed guide as always; will definitely be useful for me when Tahoe is out of Beta !
Happy to hear. Yes, one must map the ports accordingly to boot macOS Tahoe.
 

Latest posts

Forum statistics

Threads
2,084
Messages
19,451
Members
29,554
Latest member
xxxxxxxxxx