Troubleshooting

Logs

Panic tripwire — every backend panic is appended to ~/Library/Application Support/xnaut/rust-panics.log with thread and file:line. If the app ever freezes "alive" (UI up, terminals dead), check this file first — it survives even when the IPC bridge is gone.
Debug log — the app keeps a rolling debug log (byte-safe trimmed at 2 MB). Verbose per-chunk terminal logging is off by default; enable it in DevTools with window.XNAUT_VERBOSE = true when chasing output issues.
DevTools — Cmd+Option+I opens the web inspector for the UI layer.

Terminal shows nothing / black screen

Check DevTools console for Command not allowed by ACL — a Tauri 2 permission problem; update to the latest release.
Verify your shell exists (which zsh), and try a different shell in Settings → Nautify.
Run a dev build with RUST_LOG=xnaut::pty=debug cargo tauri dev to trace the PTY layer.

AI features can't reach local models

The webview blocks cross-origin requests, so xNAUT routes local-provider HTTP (model lists, chat) through the Rust backend. If Ollama/LM Studio aren't detected:

Confirm the service is running (curl localhost:11434/v1/models for Ollama).
Check the endpoint configured under Settings → AI matches the actual port.
Use the Test button — it probes from the backend (CORS-proof) and reports Connected/Failed.

The in-app update sticks on "Downloading…" (known, as of v1.11.1). The banner appears correctly, but clicking Update Now never installs; after 60 seconds it falls back to Failed — download manually. The version check works and the download never starts — release asset counts show the update manifest being fetched repeatedly while the .app.tar.gz payload sits at zero, so no client has ever retrieved it. Not a permissions problem: the updater plugin's default set already grants the full check/download/install workflow. Root cause is still open.

Until it's fixed, upgrade with brew upgrade --cask --greedy xnaut or grab the DMG from Releases.

If the banner never appears, your network may block api.github.com; install manually from the same page.

The version in the status bar looks wrong

The status bar reports the version of the code currently running, not what's on disk. If the bundle was replaced while the app was open (a brew upgrade, or a DMG copied over it), the window keeps serving the old build until you quit and relaunch — and it will keep offering you an update you already have. Check what's actually installed:

defaults read /Applications/xNAUT.app/Contents/Info.plist CFBundleShortVersionString

Filing issues

Bugs and feature requests: GitHub issues. Include the app version (About xNAUT), your OS, and the tail of rust-panics.log if the app crashed or froze.