Troubleshooting

Most kutl problems are diagnosable from a single command: kutl status. It runs from anywhere, works whether the daemon is up or not, and (with --json) produces a stable machine-readable dump suitable for pasting into support issues.

Reading kutl status

A healthy run looks roughly like this:

daemon: running (PID 12345, $KUTL_HOME=~/.kutl)
identity: Alice ([email protected])

spaces (2 registered):
  ✓ my-project   /home/alice/code/proj    relay=ws://127.0.0.1:9100/ws last-activity=12s ago
  ✗ old-test     /home/alice/scratch      <path missing>

relays:
  ws://127.0.0.1:9100/ws   reachable

Each section answers one question: is the daemon up, who am I, which spaces are registered (and are their paths still there), and can this machine reach the relays they point at.

Common situations

daemon: not running

Sync only happens while the daemon is running. Start it with kutl daemon start. If it exits immediately, check ~/.kutl/logs/daemon.log for the failure reason.

relay unreachable

Either the relay is down or this machine cannot reach it. Verify the URL with curl against the relay's HTTP equivalent. If the relay requires authentication, also check identity: in the status output.

space marked ✗

The registered path no longer exists or its .kutl/space.json is unreadable. If you moved the directory, re-register with kutl join. Stale entries are pruned automatically the next time the registry is written.

Capturing a debug bundle

To send detailed state to support:

kutl status --format json > kutl-status.json
# also include the daemon log if applicable
cp ~/.kutl/logs/daemon.log .

Verbose daemon logs

Restart the daemon with KUTL_LOG=debug to capture detailed sync activity:

kutl daemon stop
KUTL_LOG=debug kutl daemon start
# reproduce the issue
tail -f ~/.kutl/logs/daemon.log