Troubleshooting

Windows Not Tiling

• Device Control and Data Access not granted (Accessibility on macOS 26 and earlier): FazerWM cannot move or resize windows
• Screen & System Audio Recording not granted: FazerWM cannot detect the window positions or generate thumbnails
• App not signed: The permissions work only with properly signed apps

Keybindings Not Working

• Hyper key not pressed correctly: You must hold the configured right-side modifiers at the same time (default: Right Shift + Right Option)
• Conflicting shortcuts: Other apps (especially keyboard remappers) may intercept the keys before FazerWM
• Device Control and Data Access revoked: The CGEvent tap requires this permission

Setting Up the Hyper Key

The FazerWM shortcuts are built on one Hyper modifier. So they never clash with the app shortcuts. By default, the Hyper key is Right Shift + Right Option, pressed together. No single physical key produces this combination. So you map it to a real key. There are two ways to get a usable Hyper key.

Option A: Map Caps Lock with Karabiner-Elements (recommended)

Use Karabiner-Elements to turn Caps Lock into a Hyper key. Hold it for Hyper. Tap it for the normal Caps Lock. The easiest route is to install Karabiner-Elements. Then run the FazerWM setup assistant again (menu bar → Settings → Run Setup Assistant). Use its Configure the Hyper Key step to add the rule automatically. Or add it manually in Karabiner → Complex Modifications. Use a rule that maps caps_lock (held) → right_shift + right_option. Leave caps_lock on tap. If an earlier setup installed a rule that emits right_shift + right_control, remove it: Karabiner applies the first matching rule for Caps Lock, so the old rule shadows the new one.

Option B: Use all left-side modifiers (no Karabiner needed)

If you cannot install Karabiner-Elements, point Hyper at a chord that you can press directly with one hand. Use all four left-side modifiers. Edit your config:

binds:
  hyper: lctrl+loption+lcmd+lshift   # Left Ctrl + Option + Cmd + Shift

This is a genuine simultaneous chord (no remapping required). So it works on any machine. It is a bigger handful than a single Caps Lock, but it is a reliable fallback.

Windows Disappear or Are Off-Screen

• Normal behavior: Off-screen windows are "parked" at the display edges (1 px visible)
• To restore: Quit FazerWM. All windows are brought back on screen automatically.
• Wrong workspace: Switch to the correct workspace to see your windows

Display Arrangement Warning

If you see "Invalid Display Arrangement" at startup:

1. Open System Settings → Displays
2. Rearrange the displays so that each has at least one clear bottom corner
3. Make sure that no two displays overlap at the bottom-left corner and the bottom-right corner

Windows Don't Spread Across a New Multi-Monitor Setup

On the Free tier, connecting a display arrangement you have not used before in this session pulls every window onto the primary display instead of spreading them out. This is expected: multi-display use is free, but the automatic spreading on a brand-new setup is a Pro feature.

• Switch to a remembered setup: Reconnecting a display set you have already used this session restores your windows to their exact displays and workspaces, free for everyone.
• Move the windows manually: Drag them, or use the move-to-monitor keybinds, onto the other displays. They stay where you put them.
• Pro: New setups spread windows automatically by their role: primary windows to the primary, side-monitor windows to the side monitors.

High CPU Usage

• Overview mode: The overview uses continuous ScreenCaptureKit streaming. Close it when you do not need it.
• High thumbnail FPS: Reduce streamFPS in the config (default: 15, free tier: 1)

Overview Thumbnails Are Black or Empty

• Screen & System Audio Recording permission: Without it, the thumbnails cannot be captured. Grant it in System Settings → Privacy & Security → Screen & System Audio Recording. Then restart FazerWM.
• DRM-protected content: Some windows (DRM video, certain protected apps) cannot be captured by any tool. They show as black. This is a macOS limitation, not a bug.

Config Not Loading

• Check ~/.config/FazerWM/config.yaml for YAML syntax errors
• If the file is missing, FazerWM falls back to default-config.yaml from the bundle

SketchyBar Overlap

If the tiled windows overlap SketchyBar:

• FazerWM detects SketchyBar automatically at startup. Make sure that SketchyBar runs before FazerWM launches.
• After sleep or wake, FazerWM reads the bar height again automatically
• If the overlap persists on the secondary displays, restart FazerWM

See SketchyBar Integration for how detection and the workspace indicators work.

Overlays Not Visible During Screen Sharing

The FazerWM overlays (focus ring, tab tooltips, and so on) are configured to be visible when you share your screen. If they do not appear:

• Make sure that you run the latest version of FazerWM
• The overlays use the .readOnly sharing type. They appear in screen shares. They do not allow remote interaction.

Debug Panel

Open the internal debug panel from the menu bar:

1. Click the menu bar icon. Choose Debug Panel.
2. It shows: focused window info, scroll state, managed windows, parked windows, keyboard events, and license state

Permissions Revoked

FazerWM monitors the permissions every 30 seconds. If they are revoked:

• A warning dialog appears
• The status bar menu is disabled
• You can open the relevant System Settings from the dialog
• If you choose "Quit", FazerWM exits cleanly and restores all windows

Reset FazerWM

To start fresh:

1. Quit FazerWM (all windows are restored on quit)
2. Delete ~/.config/FazerWM/config.yaml to reset the config
3. Delete the Keychain entries for FazerWM to reset the license or the trial
4. Start FazerWM again. The Setup Assistant will appear.