Guides / Troubleshooting
Bridgeplay troubleshooting
Update Bridgeplay first: several reported setup and launch problems were fixed in later releases, and Check for Updates… in the app gets you the current one. Then look up the game on the compatibility list, try another graphics backend in Steam (Properties… › Bridgeplay), and if it still fails, send a report from the app so the log comes with it.
These fixes come from Bridgeplay’s documentation and from issues reported on GitHub. Bridgeplay is a hobby project maintained part-time, so help is best-effort.
Setup Assistant errors
People have reported these Setup Assistant errors. Each one has a documented fix.
| Error | What to do |
|---|---|
| Rosetta wasn’t installed because the password window was closed | Press Install to try again, and type your Mac password when macOS asks. [4] |
| Download free WineCX engine: Bridgeplay could not reach GitHub’s servers | Your connection dropped during the engine download. Since 0.7.44, Bridgeplay waits up to two minutes for the network to come back and resumes. Update Bridgeplay, then run “Set up the WineCX engine” again. [5] |
| Install Bridgeplay: Steam did not quit. Quit Steam, then try again. | Steam hung while exiting. 0.7.41 and later stop Steam in that case and continue. Update Bridgeplay and run setup again. [6] |
| Make WineCX Steam’s default: Quit Steam, then press Try Again. | Bridgeplay doesn’t change Steam’s settings while Steam is running, because Steam rewrites them when it quits. Quit Steam completely, then press Try Again. [7] [2] |
| Another tool is already set up in Steam (or “Another dylib is present”) | Another tool that modifies Steam, such as a different NotProton fork, got there first, and Bridgeplay won’t install on top of it. Use Repair Steam to put Steam back as Valve shipped it; Setup then continues by itself. [8] |
| Steam has not been set up for Bridgeplay, and this account cannot change it | Steam was installed from another macOS user account. Run setup from the account that owns Steam. [9] |
| Setup waits on App Management | Turn on Bridgeplay in System Settings › Privacy & Security › App Management. After a Bridgeplay update the switch can look on but no longer work: turn it off and on again, or remove Bridgeplay from the list with − and add it back with +. |
A game won’t launch
- Check the compatibility list. The compatibility list shows what other players found for the game, including the backend they used. Some games don’t run yet.
- Update Bridgeplay. Fixes for specific games ship in regular releases, listed in the changelog.
- “Steam is not running” in a 32-bit game. This was a bug in how 32-bit games connect to Steam on WineCX 11.17, fixed in 0.7.38. If the game is still set to an older engine, switch it to WineCX 11.17, choose Rebuild Prefix on the Prefixes page, then launch again. Back Up and Rebuild keeps a copy of the old prefix. [10]
- Games that need AVX. Some titles only run on processors with AVX. Adding
ROSETTA_ADVERTISE_AVX=1to the game’s own fix file,~/Library/Application Support/bridgeplay/gamefixes/<appid>.conf, makes Rosetta report AVX and AVX2 to the game. [3] - Online games with anti-cheat. These often won’t start at all; see below.
Black screen
- On the first launch, wait. Bridgeplay sets the game up and the game prepares its graphics, which can show a black screen for a few minutes. Later launches are quick.
- Try another graphics backend. Right-click the game in Steam, choose Properties… › Bridgeplay and change Graphics. Some games only draw correctly on one backend. Overcooked, for example, showed a solid magenta screen until it was moved to DXMT in 0.7.58. [11]
- Picture stuck in the top-left quarter. Older DirectX 9 and OpenGL games that aren’t DPI-aware can do this with High Resolution on. Turn High Resolution off for that game, or add
RETINA=0to its fix file. [3]
Steam updated and Bridgeplay stopped working
A Steam client update replaces Steam.app, which removes Bridgeplay’s patch, so Windows games won’t start until it’s back. Bridgeplay notices and puts itself back automatically. If Steam or a game is running, it waits and shows a Steam updated notice with Re-apply Bridgeplay; quit your game first if it asks. If it couldn’t do it on its own, press Try Again.
If the Status page says “Another tool changed Steam”, use Repair Steam and then install Bridgeplay into Steam again. [2]
The Status page has an optional Block Steam client updates setting. It also blocks Steam’s security fixes, so leave it off unless you have a specific reason. [1]
Controller not detected
- Allow Input Monitoring. The first time a game uses a controller, macOS asks to let Steam use Input Monitoring. If you missed the prompt, turn on Steam in System Settings › Privacy & Security › Input Monitoring.
- Steam is on in Input Monitoring but the pad still does nothing. macOS can keep Steam’s old controller permission. Turn Steam off and on again in Input Monitoring, then restart Steam.
- The controller stops working after each Bridgeplay update. Use Trust Bridgeplay on this Mac in the Setup Assistant. It adds a certificate for your Mac to your login keychain, so Steam keeps its controller permission across updates.
- DualSense over Bluetooth and Steam rumble. The DualSense Bluetooth bridge and Steam rumble forwarding that shipped in Bridgeplay 0.7.51 and earlier are paused until the same work lands in NotProton. [1]
Poor performance
- Try another backend. In Steam, Properties… › Bridgeplay › Graphics picks D3DMetal (Apple’s Game Porting Toolkit, the default when it’s installed), DXMT or DXVK. DXMT handles DirectX 10 and 11 but not 12; DXVK runs through MoltenVK. A game can run noticeably better on one of them. [3]
- The backend setting doesn’t change anything. A
BRIDGEPLAY_BACKEND=entry in the game’s Steam launch options wins over the Graphics menu. Remove it from the launch options to let the menu decide. [3] [12] - Turn High Resolution off. Drawing at your display’s full Retina resolution is sharper but slower. It is off by default.
- Upscaling and frame generation. On D3DMetal, games that offer DLSS run it on Apple’s MetalFX. Frame generation is experimental, off by default and adds a little latency. See DLSS and frame generation on Mac.
- Measure it. The Metal HUD shows frame rate and GPU details in a corner while you play, so you can compare settings.
Anti-cheat games
Online games with anti-cheat (Easy Anti-Cheat, BattlEye and others) often won’t start, and nobody can promise that anti-cheat, VAC included, won’t flag Bridgeplay. Counter-Strike 2 and Dota 2 run, but VAC keeps them off its secure servers. There is no setting that fixes this. Play online at your own risk, and check the compatibility list for what others found. Anti-cheat on Mac explains why. [1]
How to collect logs and report a problem
- A game that runs badly or not at all: after you play, Bridgeplay asks once per game how it ran. One tap posts the result with your Mac’s details and the game’s log to Compatibility reports. If you missed the prompt, right-click the game on the Prefixes page and choose Report This Game…, or use Report Your Games… in the Prefix menu. No GitHub account is needed, and your user, computer and Steam account details are removed from the log first. [1]
- Without the app: use the Game report form on GitHub.
- A problem in Bridgeplay itself (setup, Steam, updates, controllers): open a Bug report with your Bridgeplay version (bottom of the app’s sidebar), your Mac and macOS version, and these logs: [13]
~/Library/Application Support/bridgeplay/bridgeplay.logfor the app- the game’s
bridgeplay-run.log(Prefixes page › the game › Open Log) ~/Library/Logs/Bridgeplay/installer.logfor the installer
- Security problems go to a private security advisory, not a public issue. If the same problem happens with upstream NotProton and CrossOver, report it to NotProton. [13]
Sources
- Bridgeplay README (checked 29 October 2026)
- Bridgeplay AGENTS.md: rules for Steam config writes (checked 29 October 2026)
- Bridgeplay docs: per-game fixes and graphics backends (checked 29 October 2026)
- Issue #1611: Rosetta password window closed (checked 29 October 2026)
- Issue #279: engine download could not reach GitHub (checked 29 October 2026)
- Issue #158: Steam did not quit (checked 29 October 2026)
- Issue #333: Quit Steam, then press Try Again (checked 29 October 2026)
- Issue #1189: another tool already in Steam (checked 29 October 2026)
- Issue #391: Steam owned by another account (checked 29 October 2026)
- Issue #131: “Steam is not running” in a 32-bit game (checked 29 October 2026)
- Bridgeplay 0.7.58 release notes (checked 29 October 2026)
- Issue #1467: Graphics menu and BRIDGEPLAY_BACKEND (checked 29 October 2026)
- Bridgeplay issue templates (checked 29 October 2026)