Skip to main content
Version: 2.2 (dev)

Troubleshooting

Startup​

SymptomCause and fix
FATAL: no working Lua config found!the Lua libraries are not installed; sudo make install. The search order is ~/.config/somewm/rc.lua, ~/.config/awesome/rc.lua, then /etc/xdg/somewm/rc.lua or ~/.local/etc/xdg/somewm/rc.lua.
the config loads and it crashessomewm --verbose 2>&1 | tee somewm.log, -d for everything, WLR_DEBUG=1 for wlroots; look for error loading or error executing (Debugging)
an "X11 pattern detected" notificationthe config calls an X11 tool or API; Migrating has the replacement for each
black screen after loginjournalctl --user -xe | grep somewm, or dbus-run-session somewm -d from a TTY
wrong resolutionwlr-randr --output DP-1 --mode 1920x1080@60, or output.mode from Lua (Multi-Monitor)

Widgets​

A widget is not showing​

A widget with its own draw, fit or layout method, or a class with no describer, is left out of the tree with everything inside it. The log names the file and line of the method, once per class and line:

W: awesome: wibox.clay: badge defines :draw, :fit at ~/.config/somewm/badge.lua:4, which 2.1 never calls. The widget and its children are left out of the tree. See https://somewm.org/docs/guides/custom-widgets

somewm-client clay tree prints what was drawn and screen.primary.inspector = true shows it over the desktop; a left-out widget is absent from both. A property the tree cannot hold warns the same way and names what happened instead. Upgrading from 2.0 to 2.1 has the cases; Reading the tree the output.

A widget is unstyled, wrong font, no colours​

Its module was required before beautiful.init(), so every theme value it read at require time was nil, silently, and it renders in sans 8. Move the require below init (Widgets).

module 'lgi' not found. The LGI package must match the Lua version: lua51-lgi for LuaJIT on Arch, lua-lgi elsewhere (Installation). somewm -L /usr/lib/lua/5.1 points at one installed elsewhere.

No systray icons. The tray is StatusNotifierItem over D-Bus; an XEmbed-only app has no icon.

Test mode​

SymptomCause and fix
Mod4 keys do nothing in the nested windowthe host does not forward shortcuts, and the status block says ! outer compositor did not advertise shortcut inhibitor; every Mod4 is remapped to Mod1, so press Alt (per host)
nested compositor exited before IPC was readysomewm-client test logs --name <n> shows the traceback. Usual causes: a require not on the Lua path (--config sets only the rc.lua), a nested backend that needs WLR_RENDERER=pixman, or an API missing from the installed version.
test stop hangs or the state directory staysSIGTERM, five seconds, SIGKILL. If the pid is already gone, rm -rf "$XDG_RUNTIME_DIR/somewm-test/<n>" is safe.
test list shows stalethe compositor died without cleanup; test stop --name <n> removes the entry, or the rm -rf above

Input​

Keyboard layout does not switch​

grp:* XKB options need an X server. Bind it:

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

A key does not repeat when held​

If no key repeats, the rate is zero: awful.input.keyboard_repeat_rate = 25, keyboard_repeat_delay = 600. If only some keys are affected, often arrows or remapped keys, the keymap has repeat off for them. A custom ~/.config/xkb is read before the system layouts, so a symbols file X11 ignored is active here. Compile and look:

xkbcli compile-keymap --layout us | grep -A4 'key <UP>'
key <UP> {
repeat= No,
symbols[1]= [ Up ],
actions[1]= [ SetMods(modifiers=none) ]
};

A key that defines an action skips compat interpretation and stops repeating. Add repeat= yes to that key in the symbols file, re-run the command to confirm repeat= Yes, and reload.

Touchpad does nothing. awful.input.tap_to_click = 1 and the rest of Input Device Configuration.

Current limitations​

The compatibility reference lists platform differences, X-property behaviour, keyboard-layout limitations and XWayland gaps for this version.

Reporting​

Issues and Discussions on GitHub; the AwesomeWM community for Lua API questions. Include somewm --version, the relevant part of rc.lua, the somewm -d log, and the steps.