Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

👨‍⚕️ Doctor

In a nutshell

Inspect the host environment and capture a support report with acorn doctor.

Start broad, then narrow the diagnostic category:

acorn doctor
acorn doctor --check software
acorn doctor --check system,memory,network
acorn doctor --report > acorn-doctor.json

Doctor reports use the same discovery-record JSON schema as the interactive Doctor screen. The software probes cover ACORN, Chromium, Codex, Codex ACP, Git, Node.js, npm, npx, OpenCode, Ollama, ORAS, Pandoc, and Vale.

If Codex ACP is reported as missing, install its executable globally and rerun the software check:

npm install -g @agentclientprotocol/codex-acp
acorn doctor --check software

This global installation does not require npx. If npm and npx are unavailable, install Node.js/npm or download a standalone binary from the codex-acp releases and place it on PATH.

--fix applies only reversible, low-risk automatic fixes and then reports the verified host state. Package-manager and network installers require --fix --interactive: select findings with Space, preview the fixed operations with f, and confirm with y. n or Escape declines the plan. --interactive without --fix remains report-only, and --report cannot be combined with interactive mode.

Rescue: ACORN cannot find Chrome

PDF export needs Chrome or Chromium. Point ACORN at an existing executable instead of relying on automatic discovery:

# Linux
acorn --offline export index.json --format pdf \
  --chrome-path /usr/bin/google-chrome-stable

# macOS
acorn --offline export index.json --format pdf \
  --chrome-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

On Windows, pass the executable path with --chrome-path or set CHROME_PATH. Connected export can download ACORN’s pinned browser; offline export needs a configured, installed, or already cached browser. See Chrome selection.

Rescue: offline mode unexpectedly fails

Global --offline forbids network reads; it does not turn remote inputs into local ones. Check these common causes:

  1. Replace HTTP(S) inputs and model-list URLs with local paths or file:// URIs.
  2. Use check --skip prose if analyzer extensions have not already been synchronized.
  3. Configure --chrome-path or cache the pinned browser before offline PDF export.
  4. Do not combine gather --resolve, gather --merge-request, or gather --osti with offline mode.

Run the failing command with -vv to expose the resource ACORN attempted to resolve.

Rescue: a model sync target is not detected

With no target flags, acorn sync selects applications whose commands it detects. Request a target explicitly to make the decision visible:

acorn sync --vscode --dry-run
acorn sync --vscode --force --dry-run

--force bypasses command detection only for targets you explicitly include. If the application is detected but weights are elsewhere, set --models-dir; use --assume-models only when another system guarantees those paths exist. Continue with the Sync troubleshooting guide.

Next stop: Preview application routing with Sync.