Logs and diagnostics
What NALA records, how to collect a support bundle, and how to redact it before sharing.
Start with doctor
nala doctor is the first diagnostic for almost every problem. It reports what
NALA resolved rather than what it hopes is true.
nala doctor
For a machine-readable form suitable for attaching to a report:
nala doctor --json
Expected evidence: daemon reachability, resolved data directory, detected providers with their resolved paths and versions, and runtime prerequisites.
What a diagnostic contains
Diagnostic output is about your machine, so assume it includes:
- Absolute filesystem paths, including your user directory
- Repository and workspace names
- Provider names and detected versions
- Environment details relevant to launching processes
WARNING
Review diagnostics before sharing them. Paths and workspace names commonly reveal client names, unreleased project names, and your username. Redact before posting into a public issue tracker or chat.
Support bundles
The application can assemble a support bundle for a problem, including recent events and state relevant to the failure. Bundles are intended for sharing with maintainers, which means the same rule applies more strongly: read it first.
SECURITY
Never attach a support bundle, screenshot, or terminal capture that contains API keys, tokens, or credentials. NALA does not hold your provider credentials, but your own shell environment might, and captures include what is on screen.
Reading session state
Two commands answer most "is it actually doing anything" questions:
nala sessions list
nala task list
IMPORTANT
A process being alive is not evidence that work is progressing. An agent can hold a session open indefinitely without advancing a task. Trust the task state over the presence of a running process.
Escalating a problem
When reporting, include:
- The exact NALA version (
nala --version). - What you did, what you expected, and what happened.
- Redacted
nala doctor --jsonoutput. - Whether the problem reproduces on a fresh workspace.
Point 4 matters more than it looks: a problem that only appears in one workspace is usually state, and a problem that appears everywhere is usually the build.