Troubleshooting🔗

Check the Session Log🔗

Triad writes a log for each session. The manager loop keeps a symlink to the most recent one:

tail -n 200 ~/.local/state/triad/triad-latest.log

List all session logs:

ls -lt ~/.local/state/triad/

Check for syntax errors without restarting:

triad validate-config

Point at a specific file:

triad validate-config --config ~/.config/triad/config.kdl

Inside a running session:

triad msg state
triad msg workspaces

If either hangs, Triad isn't running or the socket is missing:

ls $XDG_RUNTIME_DIR/triad.sock

Check where your display manager reads Wayland session files:

ls /usr/share/wayland-sessions/
ls ~/.local/share/wayland-sessions/

Install the desktop entry to the right location:

TRIAD_WAYLAND_SESSION_DIR=/usr/share/wayland-sessions \
  tools/install_live_session.sh

Many display managers ignore ~/.local/share/wayland-sessions. Use the system path unless you know yours supports user-local sessions.

If Triad starts but no bar or shell appears, check the log for failed launch entries. Verify the shell command is on PATH:

which noctalia-shell
which waybar

If a command is missing, install it or update the profile in your config:

profile "waybar" {
  launch "waybar"
  stop   "pkill" "-x" "waybar"
}

If a bad edit prevents Triad from launching, start it with a known-good config:

triad --config ~/.config/triad/config.kdl.bak

Or reset to defaults by moving your config aside — Triad writes a starter config on first run if none exists.

Normal sessions keep behavior logs off. Enable them for a diagnostic session:

TRIAD_SESSION_DEV_MODE=1 ~/.local/bin/river-triad-session

Logs are written to:

~/.local/state/triad/behavior/

Inside a running session, toggle dev mode without restarting:

triad msg dev-mode on
triad msg dev-mode status
triad msg dev-mode off

To apply a new Triad build without losing your windows:

nimble liveReload

This builds release binaries, captures a restore snapshot, and asks the running manager to restart. Your windows stay in place.