Skip to content

Troubleshooting

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.

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 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.

The local CLI could not reach the running app.

  1. Check that Volli is open.
  2. Run volli identify from the terminal companion.
  3. Check that the terminal has VOLLI_SOCKET set.

Volli sets the socket context for terminal companions it starts. A terminal you open elsewhere may need the CLI installed and connected separately.

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.

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-body
volli 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.

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.

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.

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.

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.

Use the read-only performance diagnostics to inspect stalls recorded on this Mac:

volli perf top --since 24h
volli perf stalls --process renderer --limit 20

The 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.

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.

Include the output of volli identify and the steps that led to the problem in a GitHub issue: hussainph/volli-code.