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 logging to see what's happening. SomeWM has three log levels:

Flag	Level	Shows
(none)	error	Errors only (default)
--verbose	info	Errors + info messages
-d	debug	Everything

# Info level (recommended starting point)
somewm --verbose 2>&1 | tee somewm.log

# Debug level (verbose)
somewm -d 2>&1 | tee somewm.log

You can also set the log level at runtime from your rc.lua:

awesome.log_level = "debug"  -- or "info", "error"

For full wlroots debug output, add the environment variable:

WLR_DEBUG=1 somewm -d 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.

Test Mode

Mod4 keybindings don't work in a nested test instance

When somewm-client test start is running, the nested somewm sits inside another compositor and the host decides whether to forward Mod4. If your host (e.g. GNOME) doesn't implement the shortcut inhibitor protocol, the orchestrator auto-remaps your Mod4 bindings to Mod1 (Alt) for that instance only. Check the start block:

test 'work': pid 12345 on wayland-3 (host: wayland), config ...
  keybinds: ! outer compositor did not advertise shortcut inhibitor
            ! Mod4 combos will be intercepted by the host

When you see this, hit Alt + <key> instead of Mod4 + <key> for the duration of the test instance. See Testing with a nested compositor for the per-host compatibility table.

My test instance crashes immediately on start

The orchestrator reports nested compositor exited before IPC was ready. The crash log is in the state directory:

somewm-client test logs --name <n>

Look near the end for a Lua traceback or a wlroots error. Common causes:

• rc.lua requires a module that isn't on the test instance's LUA_PATH. The orchestrator's --config FILE only sets the rc.lua path, not the Lua search path. If your config does require("my-widgets.foo"), that module needs to be where Lua already looks (the rc.lua's directory, or ~/.config/somewm/).
• The test instance's nested-Wayland backend can't initialize. Some hosts need WLR_RENDERER=pixman instead of GLES2. Try WLR_RENDERER=pixman somewm-client test start ....
• A widget calls a SomeWM API that doesn't exist in your installed version. The log shows the unknown function name.

test stop hangs or the state dir won't go away

The orchestrator sends SIGTERM and waits up to five seconds for the IPC socket to disappear, then escalates to SIGKILL. If you see the pid file in $XDG_RUNTIME_DIR/somewm-test/<n>/ but kill -0 $(cat .../pid) says the process is gone, the compositor died ungracefully and left its state behind. Manual cleanup is safe at that point:

rm -rf "$XDG_RUNTIME_DIR/somewm-test/<n>"

test list shows a stale entry

The orchestrator's test list connects to each instance's IPC socket with a short timeout. If it can't connect, the entry is reported as stale. That usually means the compositor crashed and the cleanup didn't run.

somewm-client test list
# NAME      HOST    PID    STATE
# work      wayland 12345  stale

# Drop it
somewm-client test stop --name work

If test stop itself errors out (the pid file is unreadable, the dir is partially gone), fall back to rm -rf "$XDG_RUNTIME_DIR/somewm-test/<n>".

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
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
XKB toggle options	Use keybindings instead

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