Daemon problems
Panes stay blank, sessions do not come back, or the CLI cannot reach the daemon.
The daemon is the process that owns your sessions, tasks, artifacts, and messages. It runs separately from the desktop window, which is why closing the window does not end your work — and why daemon problems look like everything being broken at once.
Panes open but stay blank
Symptom: the desktop opens, panes appear, but nothing renders in them.
Likely causes
- The daemon is not running.
- The desktop connected to a different daemon instance than expected.
Safe diagnostic
nala doctor
Expected evidence: a daemon section reporting a reachable socket or pipe.
Repair: close the desktop fully and relaunch:
nala desktop
When not to retry: do not delete the data directory to force a fresh start
before you have read what nala doctor reports. That directory holds your
durable sessions and tasks.
The CLI cannot reach the daemon
Symptom: nala task list or similar reports a transport or connection
error.
Likely causes
- No daemon is running yet.
- Instance isolation — the CLI and the app resolved different data suffixes.
Background: NALA namespaces its entire runtime (data directory, socket, pipes) by a data-suffix environment variable. Development builds use a different suffix from packaged builds, which is how both can run side by side. A CLI started with a different suffix talks to a different daemon.
Safe diagnostic
nala doctor --json
Expected evidence: the resolved data directory and socket path. Compare it to what the running application is using.
Repair: launch the desktop once to start the daemon, then retry. If you have both a development and a packaged build installed, use the one matching the suffix you intend.
Sessions did not come back after a restart
Symptom: you reopen NALA and previous terminals or agent conversations are missing.
Likely causes
- The session passed its retention window.
- The session was explicitly stopped rather than detached.
- A crash left restore state that has not been applied.
Expected evidence: a crash-restore banner on launch when restorable state exists.
Repair: if a restore banner appears, accept it. Otherwise list what the daemon still holds:
nala sessions list
When not to retry: a stopped session is gone. Detaching and stopping are
different actions — /detach keeps a session alive, /stop ends the turn, and
quitting a session ends it.
The daemon is using more resources than expected
Symptom: sustained CPU or memory use with no active agents.
Safe diagnostic: check what the daemon still considers live:
nala sessions list
nala task list
Repair: stop sessions you no longer need. A pane that looks closed in the UI may still have a live process behind it.
NOTE
A process being alive is not the same as work being in progress. An agent can hold a session open while doing nothing. Check the task state rather than inferring from process activity.