Troubleshooting

Start with the failing action and its exact error. Note the Wuu version, selected engine, provider, and workspace before changing settings. Avoid deleting the state directory or repeatedly launching the same task: both can make diagnosis harder, and a task may already be running in the background.

Desktop startup

Quit the app completely and reopen it. Confirm that the installed build matches your platform and comes from the expected release source. If macOS blocks it, follow the installation guide rather than disabling Gatekeeper globally.

For a persistent initialization failure, keep the version and visible error. If it began after enabling a plugin, use plugin recovery and try the default interface.

A desktop window crashes or goes blank

Wuu reloads a window after a renderer crash, out-of-memory exit, abnormal exit, or launch failure. It tries automatically up to three times, at least five seconds apart. After repeated failures, a native dialog offers Reload or Close window. The retry budget resets after the page has stayed loaded for one minute. Closing a window or quitting the app cancels pending recovery.

Saved conversations remain available, and the app-server is not restarted by renderer recovery. Unsent drafts and other unsaved window state may be lost. Terminals owned by the crashed window are stopped rather than left running without a usable terminal panel; reopening the panel starts a new terminal. Other windows’ terminals are unaffected. If crashes recur, record the app version and redacted [renderer] process gone / recovery load failed messages for a report.

Model or engine unavailable

Check whether the session uses the Wuu engine or an external Codex or Claude Code executable. Configuring a model provider does not install or authenticate an external engine.

For a Wuu provider, verify the accepted model ID, connection protocol, API prefix, and authentication. An environment-backed API key must exist in the process that launched Wuu; an export in another terminal may not affect an already-running desktop app. A gateway that returns text may still fail streaming or tool calls. See model services.

wuu models is specifically a live lookup for openai-codex, not a general connection test for every provider.

Wrong workspace or missing history

Check the selected desktop workspace or CLI --workdir. A forked worktree has its own execution root, while a conversation without a workspace uses Wuu’s scratch location. Default session lists are workspace-scoped.

If the workspace folder moved, use Relocate… on its existing sidebar entry. Adding another workspace with a similar name does not repair the old workspace identity. Do not redirect a missing worktree to the main checkout without first understanding which files the task changed.

File or command refused

Read the error for the blocked path, permission mode, or sandbox backend. Read only blocks mutation; confined command execution also requires a working filesystem sandbox. An unavailable backend is a different problem from an out-of-scope path.

Register the intended workspace or correct the command before considering broader access. Unconfined is a deliberate authority change, not a general error-recovery switch. Sensitive-file guards and external-engine controls have separate rules; see permissions.

No new output

A command may have moved into a managed background process after the synchronous timeout. Inspect its state and incremental output rather than starting a duplicate. Large output can have a full-log reference even when only a tail is displayed.

A queued prompt waits for the receiving conversation. A provider failure, held turn, running tool, and completed turn are different states; use the visible error and saved trace to distinguish them. If the app is disconnected from its backend, reconnecting the UI does not prove that the underlying command stopped.

Read saved diagnostics

For a failed Wuu-engine stream, expand the error notice or the reconnect card’s Recovery details. New failures retain automatic retry counts, physical request counts, and why recovery stopped, including non-retryable errors, retry or shared-budget limits, and unsafe tool replay. These facts survive reopening the conversation. Counts describe the final failed stream, not the whole turn or billed tokens; older failures may have no recorded counts. Unknown errors are not automatically retried just because their wrapper says “request failed”.

Response data too large means one event exceeded Wuu’s local receive limit, not the model’s context-token window. SSE data payloads and Responses WebSocket messages support up to 16 MiB per event; the whole answer may span many events. Larger events stop without automatic replay or transport fallback because neither raises the limit. Ask for smaller outputs or try another model connection. Older builds can report read stream: bufio.Scanner: token too long at the former 1 MiB SSE limit; update Wuu before retrying those failures.

wuu version --long
wuu session list --json
wuu session show --json --last
wuu session trace --json --last

Run these in the relevant workspace, or supply --workdir before positional arguments. Trace reads saved events without invoking the model or replaying tool side effects. For execution-run manifests, use wuu runs; for scheduled tasks, inspect the Automation page’s run history.

Share a useful report

Include the version and operating system, desktop or CLI entry point, selected engine, minimal reproduction steps, expected result, actual result, and the relevant redacted error. Use GitHub Issues for ordinary bugs.

Do not upload the entire ~/.wuu or WUU_HOME directory. Configuration, credentials, conversations, source excerpts, tool output, artifacts, and logs may be private. Share only the necessary fragments after review. Report suspected security vulnerabilities privately through SECURITY.md.