Troubleshooting

Run the dependency checker first — it covers most common issues:

dwm-diagnostics

Or use the Control Center → System Health.

dwm Won’t Start

Black screen / returns immediately to login:

• Run dwm-diagnostics and resolve any required X11/session failures.
• Preview required packages with ./install.sh --dry-run --profile core.
• Check .xinitrc exists and ends with exec dwm
• Run startx from a TTY to see error output in the terminal

dwm: cannot open display:

• You must launch dwm from a TTY, not an existing X session
• If using a display manager, ensure dwm.desktop is in /usr/share/xsessions/

No Status Bar / Quickshell Missing

• Install the recommended desktop layer: ./install.sh --profile recommended
• Verify the managed config exists: ls ~/.config/quickshell/shell.qml
• Run manually: quickshell --no-duplicate
• Check fonts: fc-list | grep -i meslo

Terminal Won’t Open (Super+X)

• Run dwm-terminal from an existing shell to see the exact fallback message
• Run install-herdr --force if Alacritty opens but Herdr does not
• Set DWM_HERDR=0 to confirm the outer terminal works without Herdr
• Install a supported terminal: alacritty, kitty, st, warp-terminal, or xterm
• Or set a fixed terminal in config/hotkeys.toml:

  [vars]
  terminal = "alacritty"
  

Herdr is a terminal workspace, not a graphical terminal emulator. The default stack is Herdr running inside Alacritty. X11 therefore reports the window class as Alacritty, which is already covered by the terminal swallowing rules.

Browser Won’t Open (Super+B)

• Run dwm-default-apps status to inspect the current default browser
• Run dwm-default-apps browsers to list installed browser desktop files
• Set one with dwm-default-apps set-browser firefox.desktop
• Ensure xdg-utils is installed so xdg-settings, xdg-mime, and xdg-open are available

Themes Not Applying

• Confirm themes.toml is at ~/.config/dwm-titus/themes.toml
• Check the [active] section has a valid theme name
• Manually trigger: kill -USR1 $(pidof dwm)
• Run theme-apply.sh directly to see any errors

Keybinds Not Working

• Check config/hotkeys.toml for syntax errors — invalid TOML silently fails
• Verify the key name is correct (use xev to find X11 key names)
• If a bind still doesn’t work, add it as a fallback in config.h and recompile

Multi-Monitor Issues

• Tags not syncing across monitors: run dwm-diagnostics
• Cursor doesn’t follow focus: verify cursor warp is enabled in config.h (cursorwarp = 1)
• Persistent resolution or positioning: run dwm-display-setup detect, then dwm-display-setup. The wizard previews changes before writing Xorg config.
• Bad persistent layout: run dwm-display-setup rollback, then log out and back in. From a TTY, remove /etc/X11/xorg.conf.d/90-dwm-titus-display.conf if Xorg cannot start.
• TearFree is enabled only when the active Xorg driver exposes a compatible option or RandR property. Unsupported drivers are left unchanged.
• NVIDIA Full Composition Pipeline is enabled in generated persistence only when the relevant output uses the NVIDIA kernel driver and an NVIDIA Xorg provider is available, including supported hybrid configurations. Run dwm-display-setup capabilities to inspect the detected fallback before saving a layout.
• Display layout profiles: run dwm-display-profile dir and dwm-display-profile template to create optional xrandr profiles

NVIDIA / Suspend Issues

• Black screen on wake: run scripts/nvidia-suspend-test.sh to diagnose
• DPMS/screensaver issues: use Control Center -> Power, or run scripts/disable-powersaving to disable blanking and DPMS for the current session

Picom / Compositor Artifacts

Restart picom via the Control Center (Quick Actions → Restart Picom) or:

pkill picom; setsid -f picom --backend xrender

If artifacts persist, set a different backend in ~/.config/picom.conf or run with PICOM_BACKEND=glx or PICOM_BACKEND=egl.

Still Stuck?

• Open an issue: github.com/ChrisTitusTech/dwm-titus/issues
• Run the full check: bash scripts/check-deps.sh