Troubleshooting

This guide covers common issues users encounter with bspwm and how to resolve them. If you're stuck, this is the place to start.

Getting Started Issues

bspwm Doesn't Start

Symptoms: Black screen after logging in, or immediately kicked back to login manager.

Common causes and solutions:

  1. bspwmrc is not executable: bash chmod +x ~/.config/bspwm/bspwmrc

  2. bspwmrc has syntax errors: Test your config manually: bash bash -n ~/.config/bspwm/bspwmrc

Check for common issues: - Missing shebang (#!/bin/bash at the top) - Typos in bspc commands - Invalid monitor names

  1. sxhkd not starting: If sxhkd fails, you won't have any keybindings (including the one to quit).

Make sure sxhkd starts before bspwm config runs: bash # In bspwmrc: pgrep -x sxhkd > /dev/null || sxhkd &

  1. No monitors configured: bspwm needs at least one monitor with desktops: bash bspc monitor -d I II III IV V

  2. Check logs: ```bash # If using startx: cat ~/.local/share/xorg/Xorg.0.log | grep -i error

# Check bspwm socket: ls /tmp/bspwm* ```

Black Screen with Cursor

The classic "it started but nothing works" problem.

  1. Switch to a TTY: Press Ctrl+Alt+F2

  2. Check if bspwm is running: bash pgrep bspwm

  3. Check if sxhkd is running: bash pgrep sxhkd

  4. Manually test bspc: bash export DISPLAY=:0 bspc query -M

If this works, bspwm is running. The issue is likely sxhkd or your keybindings.

  1. Kill bspwm and check errors: bash pkill bspwm

Then start it manually and watch for errors: bash bspwm 2>&1 | tee /tmp/bspwm.log

Can't Open Any Programs

bspwm runs, but keybindings don't work.

  1. Is sxhkd running? bash pgrep sxhkd

If not, start it: bash sxhkd &

  1. Does sxhkdrc exist? bash ls ~/.config/sxhkd/sxhkdrc

  2. Test sxhkd manually: bash sxhkd -c ~/.config/sxhkd/sxhkdrc

Watch for error messages.

  1. Check your terminal emulator: The default sxhkdrc uses urxvt. Change it to your terminal: bash # In sxhkdrc, change: super + Return alacritty # or kitty, xterm, etc.

  2. Reload sxhkd: bash pkill -USR1 sxhkd

Display and Layout Issues

Windows Don't Tile Properly

Windows overlap, have wrong sizes, or layout is broken.

  1. Check for floating windows: A floating window looks tiled but isn't managed: bash bspc query -T -n focused | grep -i state

Force tiling: bash bspc node -t tiled

  1. Check the layout: bash bspc query -T -d focused | grep layout

If it's monocle, switch to tiled: bash bspc desktop -l tiled

  1. Reset the tree: bash bspc node @/ -B # Balance all windows bspc node @/ -E # Equalize split ratios

  2. Check for hidden windows: bash bspc query -N -n .hidden

Gaps Not Showing

  1. Check gap configuration: bash bspc config window_gap

Set it: bash bspc config window_gap 10

  1. Check if monocle gap settings are overriding: bash bspc config gapless_monocle

If you're in monocle layout with gapless_monocle=true, there won't be gaps.

  1. Check per-desktop settings: bash bspc config -d focused window_gap

Panel/Bar Not Showing

  1. Is the panel running? bash pgrep polybar # or lemonbar, dzen2, etc.

  2. Check padding: bash bspc config top_padding

Set it to match your panel height: bash bspc config top_padding 30

  1. Check if paddingless_monocle is hiding it: bash bspc config paddingless_monocle false

  2. Panel starting before bspwm? Add a delay or restart the panel after bspwm: bash # In bspwmrc: killall -q polybar while pgrep -u $UID -x polybar >/dev/null; do sleep 1; done polybar mybar &

Windows Cover the Panel

  1. Wrong stacking layer: bash bspc config -n focused layer

The window might be in the ABOVE layer: bash bspc node -l normal

  1. Fullscreen window: bash bspc node -t tiled

  2. Panel struts not set: Your panel should set EWMH struts. If using polybar, ensure: ini override-redirect = false

Multi-Monitor Issues

Monitor Not Detected

  1. Check if X sees the monitor: bash xrandr --query

  2. Check if bspwm sees it: bash bspc query -M --names

  3. Manually add the monitor: First configure with xrandr: bash xrandr --output HDMI-1 --mode 1920x1080 --right-of eDP-1

Then configure desktops: bash bspc monitor HDMI-1 -d VI VII VIII IX X

Desktops on Wrong Monitor

  1. Reset monitor configuration: bash bspc monitor eDP-1 -d I II III IV V bspc monitor HDMI-1 -d VI VII VIII IX X

  2. Set monitor order explicitly: bash bspc wm -O eDP-1 HDMI-1

  3. Check for special characters in monitor names: Names with . or other special characters need escaping: bash bspc monitor '%DVI-I-1.5' -d I II III

Monitor Swapped/Order Wrong

The desktop numbers might be assigned to the wrong physical monitor.

  1. Check current assignment: bash bspc query -M --names

  2. Reorder monitors: bash bspc wm -O DP-1 HDMI-1 eDP-1

  3. Make it permanent in bspwmrc: Put the bspc wm -O command before your bspc monitor -d commands.

Windows Lost After Monitor Disconnect

  1. Adopt orphaned windows: bash bspc wm -o

  2. Find hidden windows: bash bspc query -N -n .hidden

  3. Enable automatic monitor removal: bash bspc config remove_unplugged_monitors true bspc config remove_disabled_monitors true

Keybinding Issues

Keybinding Doesn't Work

  1. Check if the key is recognized: bash xev | grep -A2 KeyPress Press the key and note the keysym.

  2. Verify sxhkd syntax: Common mistakes: ```bash # Wrong (no space after colon): super + {h,j,k,l} bspc node -f {west,south,north,east}

# Correct: super + {h,j,k,l} bspc node -f {west,south,north,east} ```

The command must be indented with a tab, not spaces.

  1. Reload sxhkd: bash pkill -USR1 sxhkd

  2. Check for conflicts: Is another program grabbing the key? Common culprits:

  3. Desktop environments running in background
  4. ibus/fcitx input methods
  5. Screen lock utilities

Super Key Not Working

  1. Check the modifier: bash xmodmap -pm

Look for mod4. If empty, Super isn't mapped.

  1. Test with xev: bash xev | grep -i super

  2. Some laptops map Super differently: You might need to use mod4 explicitly in sxhkd, or remap with xmodmap.

Keys Work in Terminal but Not Globally

This usually means sxhkd isn't running or isn't grabbing the keys.

  1. Restart sxhkd: bash pkill sxhkd sxhkd &

  2. Check if another WM feature is interfering: Some composite managers or docks grab keys.

Focus and Pointer Issues

Focus Doesn't Follow Mouse

  1. Enable the setting: bash bspc config focus_follows_pointer true

  2. Add to bspwmrc to persist.

Focus Jumps Unexpectedly

  1. Disable focus follows pointer: bash bspc config focus_follows_pointer false

  2. Check for EWMH focus requests: bash bspc config ignore_ewmh_focus true

  3. Check if pointer_follows_focus is causing issues: bash bspc config pointer_follows_focus false

Can't Move/Resize Windows with Mouse

  1. Check pointer modifier: bash bspc config pointer_modifier

  2. Set it correctly: bash bspc config pointer_modifier mod4

  3. Check pointer actions: bash bspc config pointer_action1 move bspc config pointer_action2 resize_side bspc config pointer_action3 resize_corner

  4. Is another program grabbing the modifier?

Application-Specific Issues

Java Applications Display Gray Window

Java apps and bspwm don't always play nice.

Solution:

export _JAVA_AWT_WM_NONREPARENTING=1

Add to your ~/.profile, ~/.xinitrc, or ~/.xprofile.

For JetBrains IDEs specifically:

# In bspwmrc or .xinitrc
wmname LG3D

Steam/Games Not Working

  1. Steam client issues: Add a rule to float Steam: bash bspc rule -a Steam state=floating

  2. Games launching on wrong monitor: bash bspc rule -a 'steam_app_*' desktop='^1' state=fullscreen

  3. Game windows not focusing: bash bspc config ignore_ewmh_focus false

Electron Apps Have Issues

Some Electron apps (Discord, VS Code, Slack) have quirks:

  1. Blurry/scaled incorrectly: Add to app launch: bash --force-device-scale-factor=1

  2. Windows spawn in wrong place: Create specific rules: bash bspc rule -a Code desktop='^1' bspc rule -a discord desktop='^9'

Firefox Picture-in-Picture

bspc rule -a Firefox:Toolkit state=floating sticky=on layer=above
# Or more specifically:
bspc rule -a Firefox:Picture-in-Picture state=floating sticky=on layer=above

Performance Issues

High CPU Usage

  1. Check for runaway scripts: bash top -u $USER

  2. bspwm subscribe in a loop? If you're using bspc subscribe in scripts, make sure they're not spawning multiple instances.

  3. Panel script issues: Some panel scripts poll too frequently. Add delays or use event-based updates.

Slow Window Operations

  1. Reduce animations: If using a compositor like picom: conf # picom.conf fading = false

  2. Check for rules matching: Too many complex rules slow down window creation. Use external rules sparingly.

Recovery Commands

When things go wrong, these commands can help:

Reset to Sane State

# Focus something, anything
bspc desktop -f '^1'

# Unhide all windows
for node in $(bspc query -N -n .hidden); do
    bspc node "$node" -g hidden=off
done

# Reset all windows to tiled
for node in $(bspc query -N); do
    bspc node "$node" -t tiled
done

# Balance all desktops
for desktop in $(bspc query -D); do
    bspc node @"$desktop":/ -B
done

Emergency Quit

If you can't use keybindings:

  1. Switch to TTY: Ctrl+Alt+F2
  2. Log in
  3. Quit bspwm: bash export DISPLAY=:0 bspc quit

Restart bspwm Without Losing State

bspc wm -r

This re-executes bspwmrc but keeps your windows.

Getting Help

If you're still stuck:

  1. Check the man page: bash man bspwm

  2. Search existing issues: GitHub Issues

  3. Ask the community:

  4. IRC: #bspwm on Libera.Chat
  5. Reddit: r/bspwm

  6. Matrix: #bspwm:matrix.org

  7. Include this info when asking:

  8. bspwm version: bspwm -v
  9. Your bspwmrc (sanitized)
  10. Output of bspc query -T if relevant
  11. Any error messages