Troubleshooting

This guide covers common issues you might encounter with Config-Sway and their solutions.

General Issues

Sway won't start or crashes on startup

Symptoms: Black screen, immediate crash to TTY, or error messages on startup.Solutions:

Check for syntax errors in your configuration:
```
sway -C ~/.config/sway/config
```
Start Sway with debug logging:
```
sway -d 2> ~/sway.log
```
Then check ~/sway.log for error messages.

Verify required environment variables are set:

export XDG_CURRENT_DESKTOP=sway
export XDG_SESSION_TYPE=wayland
export XDG_SESSION_DESKTOP=sway

Check if required programs are installed:

which sway waybar mako kitty rofi swaybg

Try running Sway with a minimal config:
```
sway -c /dev/null
```

If Sway starts with -c /dev/null, the issue is in your configuration file. Comment out sections systematically to find the problematic line.

Configuration changes not taking effect

Symptoms: You edit config files but see no changes in Sway.Solutions:

Reload Sway configuration:

swaymsg reload
# or press Super+Shift+R

For theme changes, the theme file is included, so reload works. But verify the include:
```
grep "include.*theme.conf" ~/.config/sway/config
```

For Waybar changes, restart Waybar:

killall waybar
waybar -c ~/.config/waybar/config-sway.jsonc &

Check if you’re editing the correct file:

# Theme colors are in theme.conf, not main config
cat ~/.config/sway/theme.conf

Some changes (like input devices) require a full Sway restart:
```
# Save your work, then:
swaymsg exit
# Then restart Sway
```

High CPU or memory usage

Symptoms: System feels sluggish, fans spinning up, or high resource usage.Solutions:

Check for multiple swaybg processes:

ps aux | grep swaybg
# Kill duplicates
killall swaybg
~/.config/scripts/setwallpaper.sh

Check for zombie Waybar processes:

ps aux | grep waybar
killall waybar
waybar -c ~/.config/waybar/config-sway.jsonc &

Disable expensive Waybar modules:

// Temporarily disable in ~/.config/waybar/config-sway.jsonc
"modules-right": [
  // "cpu",  // Comment out CPU monitoring
  "network",
  "battery",
  "clock"
]

Reduce wallpaper resolution:

# Convert large wallpapers to reasonable size
convert input.jpg -resize 1920x1080 output.jpg

Check for runaway processes:
```
htop
# or
btop
```

Keybinding Issues

Keybindings not working

Symptoms: Pressing key combinations does nothing.Solutions:

Verify the keybinding exists in config:

grep "Super+A" ~/.config/sway/config
# Should show: bindsym $mod+a exec ...

Check for conflicting keybindings:

# List all keybindings
grep "bindsym" ~/.config/sway/config

Test if the program exists:

# For Super+F (Firefox)
which firefox

# For Super+Z (Flameshot)
which flameshot

Verify script permissions:

ls -l ~/.config/rofi/scripts/*.sh
# Should show: -rwxr-xr-x (executable)

# Fix permissions if needed:
chmod +x ~/.config/rofi/scripts/*.sh
chmod +x ~/.config/scripts/*.sh

Test the command directly:

# Run the command that should execute
~/.config/rofi/scripts/theme-switcher.sh

Multimedia keys not working

Symptoms: Volume, brightness, or media keys don’t respond.Solutions:

Check if required services are running:

# For volume keys (WirePlumber/PipeWire)
wpctl status

# For brightness
brightnessctl g

# For media keys
playerctl status

Test commands manually:

# Volume
wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+

# Brightness
brightnessctl set 5%+

# Media
playerctl play-pause

Add your user to required groups:

sudo usermod -aG video,audio,input $USER
# Log out and back in

Install missing packages:

# Arch Linux
sudo pacman -S wireplumber pipewire brightnessctl playerctl

Display and Graphics Issues

Screen tearing or artifacts

Symptoms: Visual glitches, tearing during window movement or video playback.Solutions:

Check if you’re using proprietary GPU drivers (if applicable):

# For NVIDIA
nvidia-smi

# Check loaded modules
lsmod | grep nvidia

Set environment variables for better compatibility:

# Add to ~/.config/environment.d/sway.conf
WLR_NO_HARDWARE_CURSORS=1
WLR_DRM_NO_ATOMIC=1

Try different rendering backends (for specific applications):

# Firefox
export MOZ_ENABLE_WAYLAND=1

# Chromium/Electron apps
export ELECTRON_OZONE_PLATFORM_HINT=wayland

Check Sway logs for GPU issues:
```
journalctl --user -u sway -b
```

External monitors not detected or wrong resolution

Symptoms: External displays don’t show up or use incorrect resolution.Solutions:

List all outputs:
```
swaymsg -t get_outputs
```

Manually configure outputs in ~/.config/sway/config:

# Add output configuration
output HDMI-A-1 resolution 1920x1080 position 1920,0

Force display detection:
```
swaymsg output HDMI-A-1 enable
```

Check available modes:

swaymsg -t get_outputs | grep -A 20 "HDMI-A-1"

Try disabling and re-enabling:

swaymsg output HDMI-A-1 disable
sleep 1
swaymsg output HDMI-A-1 enable

Wallpaper not displaying or wrong wallpaper

Symptoms: Black screen background or incorrect wallpaper.Solutions:

Check saved wallpaper path:

cat ~/.config/sway/wallpaper
# Verify the file exists
ls -l "$(cat ~/.config/sway/wallpaper)"

Manually set wallpaper:

killall swaybg
swaybg -i ~/.config/wallpapers/your-wallpaper.jpg -m fill &

Check for multiple swaybg processes:

ps aux | grep swaybg
killall swaybg
~/.config/scripts/setwallpaper.sh

Verify wallpaper file is not corrupted:

file "$(cat ~/.config/sway/wallpaper)"
# Should show: JPEG/PNG/WebP image data

Check setwallpaper.sh script:

bash -x ~/.config/scripts/setwallpaper.sh
# Shows execution trace for debugging

Application-Specific Issues

Rofi menus not appearing or crashing

Symptoms: Pressing Super+D, Super+Q, or other Rofi shortcuts does nothing.Solutions:

Test Rofi directly:
```
rofi -show drun
```
Check for Rofi configuration errors:
```
rofi -dump-config > /dev/null
```

Verify theme files exist:

ls ~/.config/rofi/styles/_core/
# Should include palette.rasi

Test specific Rofi scripts:

bash -x ~/.config/rofi/scripts/selector-app.sh

Check for missing dependencies:
```
# Rofi may need these
which rofi fd rg
```

Regenerate Rofi palette:

# Re-apply current theme to regenerate palette
~/.config/rofi/scripts/theme-switcher.sh

Waybar not appearing or showing incorrectly

Symptoms: No status bar visible or modules showing errors.Solutions:

Check Waybar logs:

killall waybar
waybar -c ~/.config/waybar/config-sway.jsonc -l debug

Verify config file syntax:

jsonlint ~/.config/waybar/config-sway.jsonc
# or
jq . ~/.config/waybar/config-sway.jsonc

Check if config file exists:

ls -l ~/.config/waybar/config-sway.jsonc
# If missing, re-apply theme or copy from theme directory

Disable problematic modules:

// Comment out failing modules in config-sway.jsonc
"modules-right": [
  // "custom/broken-module",
  "network",
  "clock"
]

Restart with default config:

killall waybar
waybar  # Uses default config

Flameshot screenshots not working

Symptoms: Pressing Super+Z does nothing, or Flameshot shows errors.Solutions:

Verify xdg-desktop-portal-wlr is installed and running:

# Check installation
pacman -Q xdg-desktop-portal-wlr

# Restart portal services
systemctl --user restart xdg-desktop-portal xdg-desktop-portal-wlr

Check portal configuration:

cat ~/.config/xdg-desktop-portal/sway-portals.conf

Should contain:

[preferred]
default=wlr;gtk
org.freedesktop.impl.portal.Screenshot=wlr
org.freedesktop.impl.portal.ScreenCast=wlr

Verify environment variables are set:

echo $WAYLAND_DISPLAY
echo $SWAYSOCK
# Both should have values

Check Flameshot window rule:

grep flameshot ~/.config/sway/config
# Should show: for_window [app_id="flameshot"] ...

Try alternative screenshot tool:

# Using grim + slurp
grim -g "$(slurp)" ~/screenshot.png

Kitty terminal not launching or crashing

Symptoms: Pressing Super+Enter does nothing or Kitty crashes immediately.Solutions:

Test Kitty from command line:
```
kitty
# Check for error messages
```

Check Kitty configuration:

kitty --config ~/.config/kitty/kitty.conf

Try with default config:
```
kitty --config NONE
```

Verify font is installed:

# Check for Nerd Font
fc-list | grep -i "jetbrains\|nerd"

Check for conflicting themes:

# Temporarily rename Kitty config
mv ~/.config/kitty/kitty.conf ~/.config/kitty/kitty.conf.bak
kitty  # Test with default

Theme Switching Issues

Theme switcher not showing themes

Symptoms: Theme menu is empty or shows no themes.Solutions:

Check themes directory:

ls -la ~/.config/themes/
# Should show theme directories

Verify theme structure:

# Each theme needs at minimum:
ls ~/.config/themes/Anime/sway/theme.conf
ls ~/.config/themes/Anime/wallpaper.*

Check script permissions:

ls -l ~/.config/rofi/scripts/theme-switcher.sh
chmod +x ~/.config/rofi/scripts/theme-switcher.sh

Run script with debug output:

bash -x ~/.config/rofi/scripts/theme-switcher.sh

Theme applied but colors wrong

Symptoms: Theme switches but colors don’t match or look broken.Solutions:

Reload Sway after theme switch:
```
swaymsg reload
```

Check theme.conf colors:

cat ~/.config/sway/theme.conf
# Verify color values are valid hex codes

Restart Waybar:

killall waybar
waybar -c ~/.config/waybar/config-sway.jsonc &

Verify CSS color variables:
```
cat ~/.config/waybar/colors.css
```

Re-apply the theme:

~/.config/rofi/scripts/theme-switcher.sh "ThemeName"

Performance Optimization

Slow window animations or lag

Solutions:

Reduce gaps and borders (in theme.conf):

gaps inner 0
gaps outer 0
default_border pixel 1

Disable transparency in Kitty:

# In ~/.config/kitty/kitty.conf
background_opacity 1.0

Use simpler Waybar modules:

// Remove CPU/memory monitoring
"modules-right": ["network", "battery", "clock"]

Reduce Waybar update intervals:

"cpu": {
  "interval": 10  // Update every 10 seconds instead of 1
}

Getting Help

If these troubleshooting steps don’t resolve your issue:

Check Sway logs:
```
journalctl --user -u sway -b
```
Check system logs:
```
journalctl -b | grep -i error
```

Collect system information:

# System info
uname -a

# GPU info
lspci | grep VGA

# Installed packages
pacman -Q | grep -E "sway|waybar|rofi|kitty|mako"

Test with minimal config: Create a minimal test configuration to isolate the issue.
Check upstream documentation:

Before reporting issues, ensure you’re running the latest versions of all components:

sudo pacman -Syu

Get Started

Configuration

Guides

Components

Troubleshooting

Troubleshooting

General Issues

Keybinding Issues

Display and Graphics Issues

Application-Specific Issues

Theme Switching Issues

Performance Optimization

Getting Help

Build docs developers (and LLMs) love

Get Started

Configuration

Guides

Components

Documentation Index

​Troubleshooting

​General Issues

​Keybinding Issues

​Display and Graphics Issues

​Application-Specific Issues

​Theme Switching Issues

​Performance Optimization

​Getting Help

Build docs developers (and LLMs) love

Troubleshooting

General Issues

Keybinding Issues

Display and Graphics Issues

Application-Specific Issues

Theme Switching Issues

Performance Optimization

Getting Help