Reference
Troubleshooting
The errors you are most likely to meet, and what they mean.
Start with vx doctor: it names what is missing.
| Message | Cause and fix |
|---|---|
project not initialized, run 'vx init' first | dispatch found no .vexillum/config.json. Run vx init at the project root. |
current directory is not a git repository | init needs a git repository. |
git is not installed or not on PATH (install it from https://git-scm.com) | init and doctor could not run git at all. Install git, or fix the PATH of this shell. |
cannot dispatch from here, nothing was started: followed by HERDR_WORKSPACE_ID is not set - dispatch must run from inside a herdr-managed pane, herdr is not on PATH or claude is not on PATH | dispatch and redispatch check this before creating a task, a camp or the sentinel, and list everything that is missing at once. Start Claude Code in a pane herdr manages, and install what is listed (vx doctor shows the same hints). A task whose profile uses the pi harness needs pi on PATH instead of claude, and one that uses opencode needs opencode (1.x from 1.18.29, or 2.x). |
model "sonnet" for harness pi must be provider/id (from models.json or vx dispatch) | A profile on the pi harness needs a provider/id model such as anthropic/claude-sonnet-5, and a thinking level (off to max) as its effort. See Using Pi. |
[warn] herdr integration for pi in vx doctor | herdr's Pi integration is missing or outdated, so herdr reads a Pi soldier's state off the screen. Run herdr integration install pi. |
[warn] herdr integration for opencode in vx doctor | The same for OpenCode. Run herdr integration install opencode. |
[warn] OpenCode V1 shadowing V2 in PATH in vx doctor | An older 1.x opencode comes first in PATH and hides a 2.x one. A soldier is dispatched on the first one found, so put the series you want first. |
cannot start this soldier on <model>: OpenCode has no provider ... (or ... has no model ..., or ... has no variant ...) | On OpenCode 2.x, dispatch checks the profile's provider, model and variant against what OpenCode lists for the camp and names what does exist. Fix the profile (opencode models lists the models), then vx strike the failed task. See Using OpenCode. |
the OpenCode background service is not available: ... from vx dispatch | On 2.x vexillum starts OpenCode's background service itself when it is not running, and could not. The error carries OpenCode's own message. Run opencode service status, then opencode service start, and dispatch again. |
task <id> was dispatched on opencode 2.x but opencode 1.x ... is installed now (or the reverse) from vx redispatch | A task is relaunched on the OpenCode series it was dispatched on. Install that series, or strike the task and dispatch a new one. |
running from inside ... which looks like a vexillum-managed camp | You are in a path under ~/.vexillum. cd back to the real project root. |
not running in a terminal, so nothing was changed. | init or upgrade found no terminal to ask in. Re-run with --yes (add --skills or --no-skills to decide about the skills). |
no answer (input closed or not understood) - nothing further was changed; re-run with --yes to accept without questions | A question got no usable answer, so the run stopped. Re-run, or pass --yes. |
AGENTS.md: the vexillum block was edited by hand, so it is left as it is | You edited inside the block. vx upgrade --force replaces it after saving yours to .vexillum/agents-md-slot.backup.md. See The AGENTS.md slot. |
AGENTS.md: the vexillum block is malformed | Broken markers. vx upgrade lists the repairs and asks first. |
a sentinel is already running (pid N) | Fine: there is one per machine. Do not start another. |
[warn] sentinel in vx doctor: more than one sentinel alive, a different version than the binary, or a binary changed since it started | A stale sentinel is still running after an upgrade or rebuild. It normally retires by itself within seconds; if it does not, stop the pid doctor names with kill <pid>. The next vx dispatch, vx prompt or sentinel await starts a current one. Never use pkill. See Staying current. |
vx: not found, so the sentinel Stop hook cannot wake the commander ... (stderr of the hook) or [warn] sentinel Stop hook finds vx in vx doctor | The hook's shell has no vx on its PATH and none in ~/.local/bin, Homebrew or /usr/local/bin. Install vx in one of those, or put its directory on PATH. If the hook was written with a bare vx sentinel await, run vx upgrade to rewrite it. See Sentinel. |
[warn] commanders share one wake queue in vx doctor, or one of two commanders never hears a soldier finish | Two commanders (for example Claude Code and Pi) are live in one project and a wake is delivered once, to whichever asks first. Keep one commander per project; the other can catch up with vx status and vx forum inbox. See Two commanders in one project. |
[warn] pending wakes in <project> in vx doctor, or a commander that never hears about soldiers it dispatched into another repository | Wakes are waiting in a project where no vx sentinel await runs and no commander is registered. Soldiers dispatched by this version put their wakes in the commander's own project, so these are older ones, or the commander has been idle past the await's 55 minutes. They are delivered by the next commander turn in that project, or vx sentinel drain run from it. See A commander in another project. |
.claude/settings.json has invalid JSON, leaving it untouched | Fix the JSON, then run vx init again to add the hook. |
no tasks yet in this project. after moving the project | The state key follows the path; see State. |
Landing and striking
| Situation | What to do |
|---|---|
land refused | Your checkout is dirty, or the branch diverged from the base. Commit or stash, or ask the soldier to rebase. See Parallel missions. A dirty checkout is often just init's uncommitted scaffold. |
landed, but automatic strike failed | The merge is not undone. Run vx strike <task-id> by hand. |
strike refused | The camp has uncommitted changes or unlanded commits. Land the work first. For a shipped mission the refusal says to merge the pull request and run git pull on the base branch, then retry. With gh logged in, a merged PR whose merge commit is on the local base counts as landed. See How it ends. |
strike refused: ... merge commit is not on <base> yet | The PR merged on GitHub but your local base does not have it. Run git pull on the base branch, then vx strike again. |
| The general confirmed the camp's work is already on the base or abandoned, and strike still refuses | vx strike <task-id> --discard strikes anyway and prints each commit and change it threw away. Only with the general's approval. |
strike refused: scout task ... has no report | The report is the scout's work product. Have it write the report, or pass --force. |
'gh' is not installed | ship, and landing a shipped PR, need the GitHub CLI. |
vx: tribunal failed at <step>, refusing to push or open a pull request | A tribunal step failed; nothing was pushed. Fix it in the camp and ship again. |
review blocked: N blocking finding(s) | The adversarial review found an error or warning (info never blocks). Read the findings in the output; fix them in the camp, or retry with ship --fix for the auto-fix ones. |
review blocked: incomplete coverage | The reviewer did not report reading every changed file. Ship again. |
task ... is running, not interrupted | Only an interrupted task can be re-dispatched. |
A soldier seems stuck
Check vx status. blocked is waiting on you: use decide. unconfirmed or interrupted need a look at the camp; see Blocked and interrupted. If the commander never reports a settled soldier, confirm the sentinel runs (~/.vexillum/sentinel.log) and that vx doctor reports the Stop hook as registered and finding vx ([ok] sentinel Stop hook finds vx).