Skip to content

Diagnose problems with sase doctor

This guide runs SASE's diagnostics when something looks wrong. Start here before any other Fix problems guide: the doctor names the failing area so you fix the cause, not a symptom. Every mode below is read-only.

Before you start

You need a checkout where sase runs. No provider, scheduler, or running agent is required.

1. Run the default checks

Run the bounded default set and read the summary row:

sase doctor

OK means that area is fine. WARN and SKIP still exit 0; only ERROR exits 1.

2. Narrow to one area

Re-run with detail for the area you suspect. The check id can be one check or a whole group; -L lists them all:

sase doctor -C llm.auth -v
sase doctor -L

The verbose report prints a summary, a next step, and bounded detail per check. When a page and the doctor disagree, trust the doctor output.

3. Go deeper when needed

Include the slower read-only checks, and treat warnings as failures when you need a strict answer:

sase doctor -D
sase doctor -s

The deep run adds checks that spawn real shells and contact live services. Emit JSON with -j when you are pasting a support report.

If it goes wrong

A clean doctor with a stuck run means the problem is admission or recovery, not configuration: continue with Unstick a queued agent for a run that never starts, or Recover an interrupted agent for one that died.

_[project]: A sase project is a named unit of work registered with SASE. _[workspace]: A sase workspace is a numbered clone of a project's primary repo, managed by the workspace store and tracked in that project's registry.json. _[agent]: A sase agent is an agent session or a single agent that does not belong to a session. _[prompt]: A prompt is the text SASE hands to a provider to start an agent turn. _[macro]: A macro is a reusable prompt triggered with #name in agent prompts. _[Patch]: A Patch is SASE's local unit of change. _[bead]: A bead is one tracked work item in SASE's git-native issue tracker. _[plan]: A plan is a persisted, approved artifact recording the intent behind agent work. _[TUI]: The TUI is SASE's terminal interface for running agents and reviewing results. _[epic]: An epic is an executable multi-phase plan run with sase bead work. _[gate]: A sase gate is a durable, command-backed request for one user decision, created when work must pause for the user. _[monitor]: A sase monitor is a monitor turn that runs one long command under a detached supervisor, so the command outlives the agent that started it. *[stitch]: A stitch is the lightweight ordered change record inside a Patch's STITCHES: section.