Help & troubleshooting

What actually goes wrong, and what each symptom means. Most of these fail silently, which is exactly why they are worth writing down.

Start here: nine times out of ten it is the permissions

If the app runs but nothing happens, open System Settings → Privacy & Security and check both lists — Input Monitoring and Accessibility. GamepadBridge needs both, and one alone is not enough. The entry must say GamepadBridge; if it says Terminal or iTerm, you launched the binary from a shell at some point and macOS gave the permission to that shell instead.

Installing

macOS says it added "Gerätesteuerung und Datenzugriff" — what is that?
That is macOS announcing the Accessibility permission, under a name that appears nowhere in the settings list. The notification text and the list entry do not match, which is confusing and entirely macOS's doing. Nothing has gone wrong: look for Accessibility under Privacy & Security and make sure GamepadBridge is switched on there.
I granted Input Monitoring and it still does not work
There are two permissions, not one. Accessibility is the other, and the virtual gamepad is refused without it — silently, which is why this is easy to miss. The app's menu bar shows "Virtual gamepad refused" when that happens and reopens its permission window.
Terminal says: command not found: brew
Homebrew is not installed, or your shell does not know where it lives. The Homebrew page walks through both — the second one catches most people, because Homebrew installs fine and then the PATH lines get skipped.
Why do I have to run brew trust? No other cask asks that.
Because this tap is not one of Homebrew's official ones. A cask is executable Ruby, not a config file, so Homebrew refuses to load one from a third-party source until you explicitly say you trust it. That is a good default and it is protecting you, not annoying you. Read the cask first — it is about 50 lines, mostly a URL and a checksum.
The download is tiny and will not open — a few hundred bytes of HTML
You downloaded a redirect page instead of the disk image. GitLab treats an absolute asset URL as external and answers the release permalink with an interstitial. Use the download button on the install page, which points at the package registry directly, or let Homebrew fetch it.
macOS says the app cannot be opened / is from an unidentified developer
It should not — the build is signed and notarised. If you see that, treat the copy you have as suspect rather than forcing it open: download it again from the install page or install it with Homebrew, which verifies the checksum for you.
Does it work on macOS 14 or older?
No. The virtual gamepad is built on CoreHID, which Apple introduced in macOS 15 (Sequoia). On anything older the app cannot publish a controller at all, so there is nothing to fall back to.
How do I update it?
With Homebrew, along with everything else:
Update
brew upgrade --cask gamepadbridge

Installed from the disk image? Download the current one and drag it over the old app — Finder will offer to replace it.

Permissions and first launch

GamepadBridge is not in the Input Monitoring list at all
The list only shows apps that have asked. Quit GamepadBridge from the menu bar, plug the adapter in, and launch the app again from Applications — the request happens when it first tries to open the device. Launching it from a terminal will not put it in that list, because macOS then attributes the request to the terminal.
I granted Input Monitoring to Terminal by mistake
Switch that entry off, quit the terminal completely (⌘Q, not just the window), quit GamepadBridge from the menu bar, then double-click the app in Applications. macOS asks again, and this time the request comes from the app itself.
It asked to download something from Microsoft. Is that right?
Yes, and you should say yes. The adapter needs about 200 KB of firmware that belongs to Microsoft and cannot legally ship inside the app. GamepadBridge downloads it from Microsoft, verifies it against a known checksum and stores it in ~/Library/Application Support/GamepadBridge/. It happens once, the first time an adapter is plugged in — with only an Xbox 360 receiver it never comes up.

Adapter and controller

The controller will not pair
Press the button on the adapter first, then the pairing button on the controller — within a few seconds of each other. If it still will not catch, try a different USB port: some USB-3 ports misbehave with this adapter, and putting a plain USB-2 hub in between fixes it surprisingly often. Also make sure only one copy of GamepadBridge is running.
It reports a USB access or busy error
Something else is holding the adapter. Unplug it, plug it back in, and check that a second instance of the app is not already running. You should never need sudo — on macOS the adapter is claimable as a normal user, so running anything as root here fixes nothing and is not the answer.
Does this work over Bluetooth, without the adapter?
No, and you would not want it to. Newer controllers (model 1708 and up) pair with macOS over Bluetooth on their own — nothing needed. This app exists for the adapter, and for the older controllers that only speak to it.
The Xbox 360 receiver says it is in use by Steam
Steam for Mac has a driver of its own for this receiver and takes it when it is running as the receiver is plugged in. Quit Steam, and GamepadBridge takes the receiver over within a few seconds — the menu line goes away and your controllers appear. Steam running under CrossOver does not do this.
The Xbox 360 controller's ring keeps spinning
Either it is not paired with this receiver — press the receiver's button, then the connect button on top of the controller — or the receiver sits behind a USB hub or dock. Behind one dock the receiver passed buttons through but nothing back to the controller: no ring light, no rumble. Plug it into the Mac directly.
Which controllers actually work?
On the adapter, the same ones xow supports: 1537, 1697, 1698 (Elite), 1708 and 1797 (Elite 2). On the Xbox 360 receiver, Xbox 360 wireless controllers. Model 1537 and Xbox 360 wireless controllers have been tested end to end on real hardware here, four at once. See the compatibility list for adapters and their USB IDs.

In games

The game does not see the controller
First check System Settings → Game Controllers. If the pad shows up there, macOS is happy and the problem is inside the game — many need a restart before they scan for controllers again, and some only look once at launch. If it does not show up there either, go back to Input Monitoring above.
Steam for Mac does not react to the buttons
First the good news: Steam running under CrossOver is not affected, and neither are games that use macOS's own controller support. The Mac version of Steam is built on SDL 3.4, and that is a limit GamepadBridge cannot work around: macOS marks every virtual device as connected "virtually", and SDL 3.4 then takes the pad for a wired one, which speaks a different protocol. For Xbox 360 controllers there is a way round — let Steam for Mac drive the receiver itself (start it before GamepadBridge, or quit GamepadBridge); the controllers then work in Steam, though nowhere else.
The controller does not rumble
First check the game's own vibration setting. Steam under CrossOver sets this controller up without rumble by default — switch it on in Steam's controller settings. Apps built on SDL 3.4 cannot reach the pad at all, rumble included (see above).
System Settings lists the controller several times
Versions before 1.1.0 gave macOS nothing to recognise the virtual pad by, so every start added another "Xbox Wireless Controller" to System Settings → Game Controllers. From 1.1.0 on each controller keeps a single entry. Remove the old ones there once; they do not come back.
It worked, and then a macOS update broke it
Possible, and worth knowing in advance: Apple does not guarantee that presenting a virtual controller this way keeps working across releases. If an update breaks it, please open an issue with your macOS version — that is the fastest way to a fix.

Trust and privacy

What does this app actually do on my Mac?
It talks to the adapter over USB in userspace, and publishes one virtual gamepad per controller. It installs no kernel extension, adds no login item you did not ask for, and never runs as root. Every line of it is open to read, under GPL-2.0-or-later.
Does it phone home?
Twice, and neither says anything about you. On first launch it fetches the adapter firmware from Microsoft, as described above. And once a day it downloads the list of releases from our GitLab to see whether there is an update — a plain download of one file, with no profile of your Mac attached. There is no telemetry and no account.
Why is the Input Monitoring permission needed at all?
macOS classes talking to an input device as monitoring input, whether or not you are typing on it. It is the same permission a keyboard remapper needs. Without it the device simply never opens — and, unhelpfully, with no error anywhere in the system log.

Getting in touch

How do I reach you?
Through the issue tracker on GitHub — for a bug, a question or an idea alike. A free GitHub account is all it takes, and every answer stays readable for the next person with the same problem. The code itself lives on our own GitLab, which does not take sign-ups from outside; GitHub carries a copy of it precisely so that there is somewhere open to talk.

Not covered here? Say so.

Open an issue on GitHub. Your macOS version, your adapter's USB ID and what you saw is usually enough to reproduce it.