Troubleshooting🔗

Check the Session Log🔗

Start with Triad's log summary:

triad logs

Compatibility symlinks point to the live logs. Check the session log first; it is written earliest in the startup chain and captures River, Triad, and shell output:

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

The daemon log points to the active supervised Triad process:

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

List all session logs:

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

Validate Your Config🔗

Check for syntax errors without restarting:

triad validate-config

Point at a specific file:

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

Confirm IPC Is Responding🔗

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

Session Doesn't Appear in Display Manager🔗

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.

Shell Doesn't Start🔗

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"
}

Config Edit Breaks Startup🔗

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.

Enable Diagnostic Logging🔗

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

TRIAD_SESSION_DEV_MODE=1 ~/.local/bin/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

Doctor the Live Session🔗

Run the live-session doctor when you want the checks without doing a reload:

nimble doctorLive

This checks your config, Janet assets, live binaries, supervisor metadata, and daemon identity. If the session is stale, it tells you to restart River/Triad before you reload. nimble liveReload runs these checks automatically.

Live Reload🔗

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.