Skip to main content
Version: 2.2 (dev)

Debug your config

Check the config, reproduce the error in a nested compositor, then inspect its log and runtime state.

Check Before Loading​

somewm --check ~/.config/somewm/rc.lua

The checker parses Lua and scans for recognised compatibility problems and missing imports. It does not execute the config, so a successful check does not prove that widgets, callbacks or application commands work.

The default exit threshold is warning. To return a nonzero status only for critical findings:

somewm --check ~/.config/somewm/rc.lua --check-level=critical

Reproduce a Crash in Isolation​

somewm-client test start --name debug --config ~/.config/somewm/rc.lua
somewm-client test logs --name debug -f

Use test mode to keep a compositor crash separate from your desktop. The test config still runs as your user and can modify your files.

Read Error Notifications​

The default config uses naughty to display errors. Start with the file, line number and traceback. If configuration fails before notifications are available, inspect the compositor's terminal output or test log.

Common Lua Mistakes​

Error or symptomCheck
'}' expected near a table entryMissing comma or closing brace
module '…' not foundModule spelling, file location and Lua search path
attempt to index a nil valueThe object exists and the module was required
attempt to call a nil valueFunction spelling and availability in 2.1
Theme values unexpectedly nilbeautiful.init() ran before the widget module copied those values

For a file at ~/.config/somewm/widgets/clock.lua, use:

local clock = require("widgets.clock")

Check client.focus before reading a focused window's properties because focus can be nil.

Use Log Levels​

Start a separate instance to change logging flags:

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

No flag uses error logging. --verbose adds informational messages, and -d enables debug logging, including wlroots output. To change the level in a running instance:

awesome.log_level = "debug"

Other accepted values are "error" and "info".

Debug from Lua​

Print values to the compositor log:

local gears = require("gears")
print("Tag count: " .. #root.tags())
gears.debug.dump({ focused = client.focus and client.focus.name })

For a temporary error logger:

awesome.connect_signal("debug::error", function(err)
print("Lua error: " .. tostring(err))
end)

Remove temporary handlers when finished. Adding another notification handler alongside the default one can produce duplicate alerts.

Inspect at Runtime​

somewm-client client info focused
somewm-client tag list
somewm-client screen focused
somewm-client eval "return type(require('beautiful'))"
somewm-client eval "return client.focus and client.focus.name or 'none'"

eval accepts one line. Library locals from rc.lua are not in scope, so require modules explicitly. See CLI Control for reply formatting and scripting.

Safe Reload Workflow​

  1. Edit the config and run somewm --check.
  2. Load it in the test instance with somewm-client test reload --name debug.
  3. Exercise the changed widget, rule or binding and read the log.
  4. Reload your desktop with Mod4+Ctrl+r after the test succeeds.

Reload rebuilds the Lua state. Do not rely on it to keep the old configuration if the new one fails. The config loader may try fallback configurations, so a changed wallpaper or missing custom bindings can indicate fallback.

Bisecting Errors​

Temporarily disable half the relevant code, reload the test instance and repeat with the half containing the failure. Keep required imports and initialisation in place. If the config is version-controlled, use the test-mode bisect workflow.

See Also​