Troubleshooting
A chat cannot start or has stopped
Section titled “A chat cannot start or has stopped”In Settings → All projects → Models, connect a provider and choose an available default. See Models and usage for account and tier setup.
If an existing Session has stopped, its conversation is kept. Follow Recover a Session. The status determines whether to retry, repair provider access, wait for a reset, or answer a question.
An Automation does not start automatically
Section titled “An Automation does not start automatically”Check all of the conditions for the Trigger:
- For a ticket-enter Trigger, Automatic triggers must be on for the Automation on this Mac.
- The destination column must offer the Automation and have it armed, not No automation.
- The ticket must make a new Deliberate move into the column. Enabling or arming a column does not process tickets already there.
- Another Automation may be the armed one in the column; only one Automation can fire on its own.
A switched-off Automation is still available for a manual Run. See Run an Automation and column triggers for the steps.
A scheduled Automation was skipped
Section titled “A scheduled Automation was skipped”Volli must be open and awake when the scheduled time arrives. Open the Automation’s Runs history and read the Skipped reason. Run now starts one current Run; it does not replay every missed occurrence.
A Run cannot use its Runtime
Section titled “A Run cannot use its Runtime”A saved exact model pin can become unavailable. Repair the Automation’s Runtime in its editor, or choose another model. Volli never silently falls back to a different model. A Run already in flight can also block another Run on the same ticket; wait for it to finish, or inspect the existing Session.
volli exits with code 3
Section titled “volli exits with code 3”The local CLI could not reach the running app.
- Check that Volli is open.
- Run
volli identifyfrom the terminal companion. - Check that the terminal has
VOLLI_SOCKETset.
Volli sets the socket context for terminal companions it starts. A terminal you open elsewhere may need the CLI installed and connected separately.
volli: command not found
Section titled “volli: command not found”Press ⌘, to open the separate Settings window, then choose About and
expand Diagnostics. Its CLI checks run when the page opens; a fault offers
Fix, which regenerates the parts Volli owns. Retry runs the checks
again. Use Copy report… to inspect the detected executable and shell
integration. Terminal companions opened by the app already have volli on
PATH.
A CLI response is too large
Section titled “A CLI response is too large”RESPONSE_TOO_LARGE means the app answered, but the response exceeded the
CLI’s 4 MiB limit. Narrow the request before retrying:
volli ticket list --status doing --limit 20 --json --no-bodyvolli ticket show VLT-12--no-body keeps ticket bodies out of JSON on matching app builds. Older app
builds may ignore it, so filters and --limit are still needed.
A source build cannot load the terminal module
Section titled “A source build cannot load the terminal module”node-pty must match Electron’s ABI after a dependency install. Follow
Build from source
to rebuild it. An install error needs the fix its own output names.
My ticket worktree is still on disk
Section titled “My ticket worktree is still on disk”Archiving and worktree removal are separate actions. A pinned, dirty, active, or otherwise ineligible worktree can remain on disk. Follow Clean up worktrees to inspect the reason and choose a safe removal path.
A shortcut does nothing
Section titled “A shortcut does nothing”Terminals can claim keystrokes before the app does. Click outside the terminal companion and try the shortcut again.
Single-letter shortcuts are suppressed while you are typing in a text field, editor, or dialog.
The terminal does not follow my app theme
Section titled “The terminal does not follow my app theme”A named theme in your Ghostty configuration takes precedence over Volli’s
generated colors. Remove the theme key from Ghostty and Volli terminal
settings if you want the terminal to follow the app theme. See
Theming.
MCP tools do not appear in a chat
Section titled “MCP tools do not appear in a chat”Check that the server and its tools are enabled. Existing Sessions can gain eligible additions, but new named tools wait for a cold prompt cache, compaction, or a model switch. Tools selected only for Code Mode can become usable before its next program. Start a new Session if you need the new selection immediately.
Disabling tools does not remove them from an existing Session’s recorded surface. A disabled server still refuses calls and asks you to enable it in Settings. Start a new Session to use a reduced tool selection. Follow MCP servers for discovery failures, unsupported authentication, and deletion limits.
The app stalls or responds slowly
Section titled “The app stalls or responds slowly”Use the read-only performance diagnostics to inspect stalls recorded on this Mac:
volli perf top --since 24hvolli perf stalls --process renderer --limit 20The output identifies known operations, interaction labels, and builds. Missing attribution means the cause is unknown. Include the relevant rows with your reproduction steps. See CLI commands for filters and build comparisons.
Where Volli keeps things
Section titled “Where Volli keeps things”See Local data and network access for storage locations. Removing a project from Volli does not delete its repository folder. The JSON export is not a restorable backup; see Manage local storage.
Report a bug
Section titled “Report a bug”Include the output of volli identify and the steps that led to the problem in
a GitHub issue: hussainph/volli-code.