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:

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: