Reference / Troubleshooting

Troubleshooting

Most problems are an agent that is not installed yet, or one that needs you to sign in.

An agent shows as not installed

Click Add or Install next to it in Settings, Agents, or choose it in a new session's agent picker (it is labelled "not installed") and click Install. Zorvo brings Node.js when yours is missing or older than 22, and uv for agents that need it.

A registry agent also counts as installed when its binary is on your PATH or its npm package is installed globally. Then click Check again in Settings.

An agent needs you to sign in

Its status reads Sign in in the Agents menu and in Settings, Agents. Use a sign-in method the card offers, or sign in once in a terminal, then click Check again. Zorvo reads your shell's settings again first, so a key you just added to ~/.zshrc is found. Your message is sent once you are signed in. See Signing in.

A turn failed

A row under the last message says what happened. When the agent could not reach the network, it says so in plain words and keeps the agent's own error behind Details.

• Try again sends your last message once more. It is off while a turn runs, and an agent that has exited is reopened first.
• Other errors show the agent's own text.

An agent seems stuck

Under the line that says the agent is working, Zorvo shows a notice with a Stop button when the agent reports failed requests in a row (for Qwen Code, with the error it logged), or has sent nothing for a minute while no tool is running. Click Stop to end the turn, or wait if the agent is working on something long.

Gemini CLI does not answer

Gemini's default model, auto, can hang without an answer. Pick another model in the composer's model chip. Zorvo sets it before your first message, and your next session starts with it.

An agent does not start

When you click Install and your Node.js is missing or older than 22, Zorvo installs Node.js for Claude Code, Codex and Qwen Code. The first start downloads the agent's pinned package, so it can take a moment.

No pull request status

Open Settings, GitHub. It says when the GitHub CLI is missing, with brew install gh to copy. When you are signed out, Connect opens a terminal where gh signs you in through your browser. The Changes tab links there too. A repository without a GitHub remote has no pull requests to show.

An update does not install

• Opened from the disk image. A copy in a read-only place cannot update itself. Drag Zorvo into Applications, open it from there and update again.
• Older than 0.6.0. Update once by hand: download the newest .dmg and replace Zorvo in Applications. See Update Zorvo.

A worktree would not have it

The message "is not in the last commit, so a worktree would not have it" means a worktree checks out the last commit. Commit the folder first, or turn off New worktree.

The app is blocked on first open

The build is not signed yet. See Download and open.