BetterStageDocs / Troubleshooting
Troubleshooting
Running into an issue? Find solutions to the most common problems below. Each card covers a specific symptom and how to resolve it.
Permissions
“BetterStage can’t control my windows”
BetterStage requires the Accessibility permission to read and move windows. Open System Settings > Privacy & Security > Accessibility and make sure BetterStage is listed and enabled. If it was already enabled, try toggling it off and on again. Restart BetterStage after changing the permission.
“Keyboard shortcuts aren’t working”
BetterStage uses the native Carbon hotkey API for keyboard shortcuts, so no Input Monitoring permission is needed. If shortcuts aren’t working, first check that the Accessibility permission is enabled. Also verify that no other application is using the same key combinations — conflicting shortcuts will prevent BetterStage from receiving the events.
“Windows aren’t detected”
Window detection uses the macOS Accessibility API, which is covered by the Accessibility permission. Make sure it is enabled in System Settings > Privacy & Security > Accessibility. Note that some applications use non-standard window types (such as floating panels or custom Chrome windows) that may not be detected by the accessibility API.
Window Behavior
“Firefox/Chrome windows animate instead of snapping instantly”
Some browsers (Firefox, Chrome, and Electron-based apps) enable an accessibility flag called AXEnhancedUserInterface that causes window moves to animate instead of snapping. BetterStage automatically detects and disables this flag for affected apps. If you still see animated moves, try quitting and reopening the browser so BetterStage can reapply the fix.
“Finder appears when switching to an empty stage”
This is expected macOS behavior. When all regular apps are hidden, macOS automatically activates Finder. BetterStage mitigates this by using position-based hiding instead of app-level hiding when switching to empty stages, but Finder may still briefly appear in some cases.
“Windows are missing after a crash”
BetterStage saves window state continuously and includes a crash handler that attempts to unhide all windows before exiting. If a hard crash occurs and windows are still hidden, simply relaunch BetterStage. On startup, it runs a reconciliation process that discovers all on-screen windows and unhides any that were left in a hidden state. All windows will be restored to their original positions.
App Configuration
“Running from terminal vs .app bundle”
When you run BetterStage via swift run in a terminal, macOS attaches the Accessibility permission to your terminal app rather than to BetterStage itself. For proper permission handling where BetterStage appears by name in System Settings, build and run the.app bundle instead.
“Stages bar won’t appear”
The stages bar can be triggered via the hot edge (moving your cursor to the top of the screen) or with the keyboard shortcut Opt+Up Arrow. Make sure the hot edge is enabled in Settings. If the stages bar still does not appear, check that BetterStage has the required Accessibility permission.
“Monitor not recognized after reconnecting”
BetterStage uses macOS display IDs to track monitors. In rare cases, macOS may assign a new display ID when a monitor is reconnected (especially after driver updates or using a different port). Try disconnecting and reconnecting the monitor, then restart BetterStage. If the monitor still is not recognized, re-configure it in Settings > Monitors.
Still need help?
If your issue is not covered above, reach out and we will help you get things working.