Troubleshooting

Solutions to the most common issues encountered when using Verun. Each scenario follows a Symptom → Cause → Resolution pattern.

Agent Not Found / "command not found"

Symptom: Starting a session fails with command not found or agent not found.

Cause: The agent CLI (e.g., claude, codex, gemini) is not installed or not in your system PATH.

Resolution:

1. Verify the CLI is installed by running the command directly in your terminal:

   claude --version

2. If the command is not found, install the agent CLI following its official documentation:
   • Claude Code
   • OpenAI Codex
   • Google Gemini
3. Restart Verun after installing the CLI.

Worktree Creation Fails

Symptom: Creating a task fails with a worktree error.

Cause: The repository has a dirty working tree (uncommitted changes) or is in a detached HEAD state.

Resolution:

1. Check for uncommitted changes:

   git status

2. Commit or stash your changes:

   git stash

3. Verify you are on a valid branch (not detached HEAD):

   git branch

4. Retry creating the task.

App Fails to Launch on macOS (Gatekeeper)

Symptom: macOS shows "Verun cannot be opened because the developer cannot be verified."

Cause: macOS Gatekeeper blocks apps not distributed through the App Store.

Resolution:

1. Right-click the Verun app and select Open.
2. Click Open again in the confirmation dialog.
3. Alternatively, allow it in System Settings → Privacy & Security → click Open Anyway.

Or from the terminal:

xattr -cr /Applications/Verun.app

Project Setup Commands Fail

Symptom: Task creation succeeds but setup commands (from .verun.json) fail.

Cause: Missing .env file, unmet dependencies, or incorrect commands in the setup array.

Resolution:

1. Check that the commands in .verun.json work when run manually in the project directory:

   cp .env.example .env
   npm install

2. Ensure .env.example exists before referencing it.
3. Check that all required dependencies are installable without interactive prompts.
4. Review the task's error output in the terminal panel for specific failure messages.

App Auto-Update Fails or Hangs

Symptom: Verun shows an update notification but the update does not complete.

Cause: Network issues, insufficient disk space, or file permission problems.

Resolution:

1. Check your internet connection.
2. Ensure at least 500 MB of free disk space.
3. Download the latest version manually from the Releases page and replace the existing installation.
4. On Linux, ensure the AppImage has execute permissions:

   chmod +x Verun_amd64.AppImage

Session Disconnects Unexpectedly

Symptom: An active agent session stops responding or disconnects.

Cause: The agent CLI process crashed, or the machine went to sleep.

Resolution:

1. Check the terminal panel for error output.
2. Restart the session by clicking Start Session on the same task.
3. Sessions are resumable — the agent can pick up where it left off.
4. If the issue persists, check the agent CLI's documentation for known issues.

Diff Viewer Shows No Changes

Symptom: The diff viewer is empty after an agent session.

Cause: The agent did not make any file changes, or changes were committed and the diff viewer is showing the working tree (which is clean).

Resolution:

1. Switch the diff viewer to show commits instead of working-tree changes.
2. Check the task status — if the agent session ended without making edits, there is nothing to show.
3. Verify the task's worktree path is correct in the task details.

PR Creation Fails (No Remote Configured)

Symptom: Creating a pull request from within Verun fails.

Cause: The repository does not have a git remote configured, or the remote URL is incorrect.

Resolution:

1. Check the configured remote:

   git remote -v

2. Add a remote if none exists:

   git remote add origin https://github.com/your-org/your-repo.git

3. Ensure the branch has been pushed before creating a PR:

   git push -u origin your-branch-name