Troubleshooting
Startup checks after an update
Howse 0.40.0 discards an earlier successful workspace check when the window reloads or the renderer fails. During a local app replacement, the old app backup is removed only after the newly installed app answers a fresh workspace check. If the current window is not ready, the backup is kept for recovery.
The app takes a long time to open
On Mac, update to Howse 0.30.0 or later if the window takes a long time to appear. This release reduces repeated recovery work for completed context records and improves startup scanning. Startup time still depends on the amount of stored data and your environment.
Core updates take effect on the next app launch. Wait for active work to finish before restarting; you do not need to delete your data or context records.
An agent won't run
- CLI missing or sign-in required: open Settings → Agent tools to check installation, version, and sign-in status. Copy the suggested setup command or open the official documentation. On macOS, Sign in in Terminal opens Terminal; on Windows, sign in from your own terminal. Choose Recheck when finished. A confirmed sign-in requirement prevents the agent from starting; Sign-in unknown alone does not.
- CLI too old: update it to the minimum version listed in Requirements or later. For example, Claude Code CLI needs 2.1.260 and Codex CLI needs 0.154.0.
protectedwon't start: Howse couldn't confirm the required protections. Check the CLI version, or switch toautomatic.- Stuck at
waiting_limit: the number of runs chained from one request hit theHOWSE_MAX_CHAIN_TURNSlimit. The default is 0, which means no limit. Raise the limit and restart the app to continue.
Stopping and retrying
| To | Use | Result |
|---|---|---|
| Stop everything in a thread | Stop all (in the Manage list) | Stops runs, pending waits, and follow-up work in this thread. Other threads keep going. |
| Stop one task | Stop task (in the run bar or the Manage list) | Stops that task and any runs that came from it. |
| Retry a failed run | Retry in same session or Retry in new session | Creates one new run of the same task. A new session replaces only that task's session. |
| Clear a failure from the list | Dismiss | Removes it from the needs-attention list. Nothing is deleted. |
- You can retry a turn you stopped; the retry starts a new recovery and doesn't revive its cancelled sibling or child runs. A run from a session that was replaced can't be retried. Continue from the role's current session. If the role is archived, restore it first.
- Retrying doesn't undo earlier effects, such as file changes.
- If the disk is full and a finished run's end can't be saved, it can keep showing as running. Once saving works again, Howse closes it as failed (
run_state_unsaved), and you can retry it. - A run in
termination_unknownis never rerun automatically. Make sure the process has actually exited, mark it as terminated, then retry.
Failed turns are managed in the run list without a duplicate interrupted card in the conversation. Acknowledged older error cards are hidden. A normally finished turn can complete silently when its final response is empty, without an extra provider run or a generated message. An explicitly empty Codex final response does not reuse earlier progress text as the final result. Acknowledged errors are also hidden in run details.
Did my message arrive?
In the channel list, reactions show each participating agent’s latest run in the thread, including retries and continuations. A completed continuation updates that agent’s channel reaction to ✔️. Reactions inside the thread still describe the individual message.
- 👀 means the agent received it. 💬 means a run actually started working on it. Neither one means the agent understood it.
- If it's unclear whether a message was delivered (after a dropped connection, for example), Howse doesn't resend it automatically. Instead, it marks the message as unconfirmed so the work doesn't run twice.
What happens when I quit?
- Running agents are stopped. Queued work and tasks waiting on a person or a teammate are kept.
- On the next launch, Howse doesn't guess whether an interrupted run succeeded or was canceled.
Where are my data and logs?
- Agents and conversations: the app's
userData/datafolder, outside the app bundle. - Howse's records for a project:
.howse/in the project folder. - Per-run records and error logs:
run.json,events.jsonl, andstderr.logunder.howse/run/<run ID>/. - Whyve records:
context/in the project folder.
Port conflicts
Howse runs a local server inside the app and binds it only to 127.0.0.1.
Recovery and run controls in 0.46.0
Update manually and restart after current work finishes if an orphaned question record prevents startup or an orphaned pending item causes Stop all to fail. This release skips those missing-message records without deleting your data. An already open stop/retry confirmation also follows the current execution lock. Empty or omitted optional Codex instructions no longer fail native validation.