TUI problems
The terminal agent will not start, will not respond, or looks stuck.
nala opens a CLI instead of the TUI
Symptom: running nala produces command output rather than the agent
interface, or reports an unknown command.
Likely causes
- The build predates the TUI entry point.
- The invocation name was not detected as
nala.
Both nala and wmux point at the same bundle, and the invocation name routes
subcommands. Some paths are reachable only when invoked as nala.
Safe diagnostic
nala version
nala doctor
Repair: update to the current preview and retry from a new terminal.
The composer accepts input but nothing happens
Symptom: you type, submit, and the transcript never moves.
Likely causes
- No provider is authenticated.
- The session never reached the daemon.
Expected evidence: the header should move through acknowledgement into a thinking state. Chrome is gated on real evidence, so a header that never leaves its initial state means submission was not acknowledged.
Repair: check the provider first — see provider problems — then the daemon.
When not to retry: do not submit the same message repeatedly. Each submission queues; you will end up with the request pending several times over. See delivery lifecycle.
It says unknown and I want a real answer
Symptom: delivery or status shows unknown.
This is not a bug. The classifier reports state from observable evidence and
declines to guess when the evidence is absent. unknown means "I cannot prove
either way," which is more useful than a confident wrong answer.
Repair: look at the agent directly. If it is a provider pane, read the pane.
A turn will not cancel
Symptom: /stop does not end the in-flight turn.
Likely cause: the provider is not responding to cancellation.
Repair: /stop, then inspect the provider's own pane. If the provider
process is wedged, the session is the level to act at, not the TUI.
IMPORTANT
/stop cancels a turn. /detach releases your terminal and leaves the
session running. /quit exits. Reaching for the wrong one is the most common
way people lose work here.
Scrollback or rendering looks wrong
Symptom: the transcript renders oddly, duplicates, or scrolls unexpectedly.
Context: the TUI renders diff-based frames and maintains a conversation projection that deduplicates prompt echoes and coalesces streaming and tool lifecycle events. Rendering issues are usually terminal-capability related.
Safe diagnostic
nala doctor
Repair: try a different terminal emulator to isolate capability problems. An explicit edge-case registry handles known degradations, so a reproducible rendering failure in a common terminal is worth reporting with the terminal name and version.
Errors mention DAEMON_*
Transport errors are distinct from model errors by design:
| Code | Means |
|---|---|
DAEMON_NOT_CONNECTED | No daemon reachable |
DAEMON_TIMEOUT | Daemon did not respond in time |
DAEMON_CANCELLED | The call was cancelled |
DAEMON_RPC_ERROR | The call failed at the daemon |
These are infrastructure, not the model refusing. Go to daemon problems.