Troubleshooting

“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. If the permission is revoked while BetterStage is running, the app alerts you and restores hidden windows instead of leaving them off-screen. Revoking Accessibility no longer lets BetterStage hold keyboard or mouse input. Re-granting it does not interrupt an in-flight Saved Workspace, Continuity, or Wake restore.

“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, mouse buttons, or trackpad gestures — conflicting shortcuts will prevent BetterStage from receiving the events. Rebind keyboard, mouse, and trackpad controls in Settings > Shortcuts.

“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.

“Should I use BetterStage with macOS Stage Manager?”

No. Turn off Apple's built-in Stage Manager before using BetterStage. Both tools manage window visibility, so running them together can cause confusing switches, hidden windows, or windows appearing in the wrong place. Open System Settings > Desktop & Dock > Stage Manager and turn Stage Manager off, then relaunch BetterStage if the workspace still looks wrong.

“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.

“Firefox windows flash, resist placement, or lag behind stage switches”

Firefox handles its windows in non-standard ways, so it doesn’t always cooperate with window management — you may see windows briefly flash, resist precise placement, or lag behind stage switches. This is a known issue and we’re continuing to improve Firefox compatibility.

“Finder appears when switching to an empty stage”

macOS can activate Finder when the foreground application has no visible windows. BetterStage 2.2.0 hides individual windows in a private Space rather than hiding the entire application. If a window unexpectedly appears on an empty Stage, report the app name and the sequence of Stage or desktop switches that triggered it.

“Windows moved to the wrong stage after sleep or screen saver”

Let the display arrangement settle. A remembered display's layout returns on its own; if a recovery prompt appears, choose Restore Workspace or Keep Current Layout. For windows that remain hidden after a Desktop was removed, or landed off-screen after a display change, use Rescue Windows from the menu bar. If BetterStage reports that macOS Spaces are unavailable, finish the Desktop transition and choose Retry. Restart BetterStage if the problem continues.

“A dialog or floating window is stuck behind TabStack”

Open the Snap Wheel and choose Raise Floats from More Actions. That brings floating and untracked windows on this monitor forward without changing the layout or revealing hidden tabs. Rescue Windows also recovers windows BetterStage hid in private Spaces, including windows whose original Desktop was removed.

“Windows are missing after a crash”

BetterStage records windows moved into private Spaces and runs a separate recovery helper. If BetterStage exits unexpectedly, the helper uses those records to return hidden windows to their saved Desktops. If windows are still missing, relaunch BetterStage and use Rescue Windows. A removed Desktop or disconnected display may require a reachable replacement destination.

“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.

On built-in Mac displays with a notch, Settings > Stages > Stages Bar > Avoid the display notch can skip the notch itself while keeping the rest of the top edge active.

“Monitor not recognized after reconnecting”

BetterStage recognizes monitors by hardware details such as model and serial number, not only the display ID macOS assigns. In rare cases, for example after a driver update or with a different port or adapter, those details change. Try disconnecting and reconnecting the monitor, then restart BetterStage. If the monitor still is not recognized, re-configure it in Settings > Displays.

“⌘Tab still shows the macOS app switcher”

The BetterStage ⌘Tab Switcher is optional and off by default. Turn on Use BetterStage ⌘Tab in Settings > ⌘Tab Switcher and make sure Pro, the trial, or a daily Pro preview is active. Without previews it shows app icons; allow Screen Recording for live thumbnails. See the ⌘Tab Switcher guide.

“My Stages don’t load after going back to 2.0.x”

Stages saved by BetterStage 2.2 can’t be opened by earlier versions. If you reinstalled 2.0.x, your Stages won’t load; update to the latest version from the download page instead.

BetterStage keeps a rolling diagnostic log capped at 10 MB so it never fills your disk. To attach it to a bug report, open the BetterStage menu bar icon and pick Reveal Diagnostic Log… — Finder opens to the log file so you can drag it into a Discord message, GitHub issue, or email.

Release builds avoid verbose logging that would capture window titles. If you're reproducing an issue and want the richer trace, run a beta or release-candidate build, capture the log, then return to the release channel afterwards.