Troubleshooting

Startup Issues

"No config found" error

Make sure you ran make install (or make install-local). Running SomeWM directly from the build directory won't work because Lua libraries aren't in the expected paths.

After installation, SomeWM searches for configs in this order:

1. ~/.config/somewm/rc.lua
2. ~/.config/awesome/rc.lua
3. /etc/xdg/somewm/rc.lua (system install) or ~/.local/etc/xdg/somewm/rc.lua (local install)

Config loads but crashes immediately

Enable debug logging:

somewm -d 2>&1 | tee somewm.log

Or with full wlroots debug output:

WLR_DEBUG=1 somewm 2>&1 | tee somewm.log

Look for lines containing error loading or error executing.

"X11 pattern detected" notification

Your config contains code that won't work on Wayland. Edit your rc.lua to remove or replace X11-specific patterns. See Migrating from AwesomeWM.

Widget Issues

Widgets not rendering / LGI not found

SomeWM requires LGI for widget rendering. The package must match your Lua version:

Lua Version	Arch Linux	Debian/Ubuntu	Fedora
LuaJIT (default)	lua51-lgi	lua-lgi	lua-lgi
Lua 5.4	lua-lgi	lua-lgi	lua-lgi

For custom LGI locations:

somewm -L /usr/lib/lua/5.1

Systray icons not showing

SomeWM uses the SNI D-Bus protocol. Legacy apps that only support X11 _NET_SYSTEMTRAY won't show icons.

Most modern apps (NetworkManager, Discord, Bluetooth applets) support SNI.

Input Issues

Keyboard layout not switching

XKB toggle options like grp:alt_shift_toggle don't work automatically on Wayland. Use explicit keybindings:

awful.key({ "Mod1", "Shift" }, "space", function()
    local current = awesome.xkb_get_layout_group()
    awesome.xkb_set_layout_group((current + 1) % 2)
end)

Touch input not working

Make sure libinput is properly configured. Check awful.input settings:

awful.input.tap_to_click = 1

Display Issues

Black screen after login

Check logs for errors:

journalctl --user -xe | grep somewm

Try running from TTY with debug output:

dbus-run-session somewm -d

Wrong resolution

SomeWM uses wlroots for output configuration. You can use wlr-randr to configure outputs:

wlr-randr --output DP-1 --mode 1920x1080@60

Current Limitations

These features are not yet implemented:

Feature	Status	Notes
Systray (XEmbed apps)	Partial	SNI works, XEmbed doesn't
root.fake_input()	Stub	Virtual input not implemented
root.cursor()	Stub	Cursor theme changing
X property APIs	Stub	X11 doesn't exist on Wayland
Keybinding removal	Stub	root._remove_key() is no-op
WM restart	N/A	Wayland architecture limitation

Partially Implemented

Feature	Status
Strut aggregation	Single panel works
XKB toggle options	Use keybindings instead
Scroll wheel bindings	On root/clients TODO

Getting Help

1. Check GitHub issues
2. Join GitHub Discussions
3. Visit AwesomeWM community (for Lua API questions)

When reporting issues, include:

• SomeWM version (somewm --version)
• Your rc.lua (or relevant snippets)
• Debug log output (somewm -d)
• Steps to reproduce