Referencia
Solución de problemas
Los errores que más probablemente encuentres, y qué significan.
Empezá con vx doctor: te dice qué falta. Los mensajes de error de vexillum están en inglés y se citan tal cual.
| Mensaje | Causa y solución |
|---|---|
project not initialized, run 'vx init' first | dispatch no encontró .vexillum/config.json. Corré vx init en la raíz del proyecto. |
current directory is not a git repository | init necesita un repositorio git. |
git is not installed or not on PATH (install it from https://git-scm.com) | init y doctor no pudieron ejecutar git. Instalá git, o arreglá el PATH de esta shell. |
cannot dispatch from here, nothing was started: seguido de HERDR_WORKSPACE_ID is not set - dispatch must run from inside a herdr-managed pane, herdr is not on PATH o claude is not on PATH | dispatch y redispatch lo revisan antes de crear una tarea, un camp o el sentinel, y listan todo lo que falta de una vez. Iniciá Claude Code en un pane que herdr administre e instalá lo que figure (vx doctor muestra las mismas indicaciones). Una tarea cuyo perfil usa el harness pi necesita pi en el PATH en lugar de claude, y una que usa opencode necesita opencode (1.x desde 1.18.29, o 2.x). |
model "sonnet" for harness pi must be provider/id (de models.json o de vx dispatch) | Un perfil en el harness pi necesita un modelo provider/id como anthropic/claude-sonnet-5, y un nivel de thinking (off a max) como effort. Ver Usar Pi. |
[warn] herdr integration for pi en vx doctor | Falta la integración de Pi de herdr o está desactualizada, así que herdr lee el estado de un soldier de Pi de la pantalla. Corré herdr integration install pi. |
[warn] herdr integration for opencode en vx doctor | Lo mismo para OpenCode. Corré herdr integration install opencode. |
[warn] OpenCode V1 shadowing V2 in PATH en vx doctor | Un opencode 1.x más viejo va primero en el PATH y tapa a uno 2.x. Un soldier se despacha con el primero que se encuentra, así que poné primero la serie que querés. |
cannot start this soldier on <model>: OpenCode has no provider ... (o ... has no model ..., o ... has no variant ...) | En OpenCode 2.x, dispatch comprueba el provider, el modelo y el variant del perfil contra lo que OpenCode lista para el camp y nombra lo que sí existe. Corregí el perfil (opencode models lista los modelos) y después hacé vx strike de la tarea fallida. Ver Usar OpenCode. |
the OpenCode background service is not available: ... desde vx dispatch | En 2.x vexillum levanta él mismo el servicio en segundo plano de OpenCode cuando no está corriendo, y no pudo. El error trae el mensaje del propio OpenCode. Corré opencode service status, después opencode service start, y despachá de nuevo. |
task <id> was dispatched on opencode 2.x but opencode 1.x ... is installed now (o al revés) en vx redispatch | Una tarea se relanza en la serie de OpenCode con la que se despachó. Instalá esa serie, o hacé strike de la tarea y despachá una nueva. |
running from inside ... which looks like a vexillum-managed camp | Estás en una ruta bajo ~/.vexillum. Volvé con cd a la raíz real del proyecto. |
not running in a terminal, so nothing was changed. | init o upgrade no encontró una terminal donde preguntar. Volvé a correr con --yes (sumá --skills o --no-skills para decidir sobre las skills). |
no answer (input closed or not understood) - nothing further was changed; re-run with --yes to accept without questions | Una pregunta no tuvo una respuesta utilizable, así que la corrida se detuvo. Volvé a correr, o pasá --yes. |
AGENTS.md: the vexillum block was edited by hand, so it is left as it is | Editaste dentro del bloque. vx upgrade --force lo reemplaza después de guardar el tuyo en .vexillum/agents-md-slot.backup.md. Ver El slot de AGENTS.md. |
AGENTS.md: the vexillum block is malformed | Marcadores rotos. vx upgrade lista las reparaciones y pregunta antes. |
a sentinel is already running (pid N) | Está bien: hay uno por máquina. No inicies otro. |
[warn] sentinel en vx doctor: más de un sentinel vivo, otra versión que el binario, o un binario que cambió desde que arrancó | Un sentinel desactualizado sigue corriendo después de un upgrade o rebuild. Normalmente se retira solo en segundos; si no, detené el pid que nombra doctor con kill <pid>. El siguiente vx dispatch, vx prompt o await del sentinel arranca uno al día. Nunca uses pkill. Ver Mantenerse al día. |
vx: not found, so the sentinel Stop hook cannot wake the commander ... (stderr del hook) o [warn] sentinel Stop hook finds vx en vx doctor | El shell del hook no tiene vx en su PATH ni hay uno en ~/.local/bin, Homebrew o /usr/local/bin. Instalá vx en alguno de esos lugares, o poné su directorio en el PATH. Si el hook se escribió con un vx sentinel await pelado, corré vx upgrade para reescribirlo. Ver Sentinel. |
[warn] commanders share one wake queue en vx doctor, o uno de dos commanders nunca se entera de que un soldier terminó | Dos commanders (por ejemplo Claude Code y Pi) están vivos en un mismo proyecto y un wake se entrega una sola vez, al primero que lo pide. Mantené un commander por proyecto; el otro puede ponerse al día con vx status y vx forum inbox. Ver Dos commanders en un proyecto. |
[warn] pending wakes in <project> en vx doctor, o un commander que nunca oye a los soldiers que despachó en otro repositorio | Hay wakes esperando en un proyecto donde no corre ningún vx sentinel await ni hay un commander registrado. Los soldiers despachados por esta versión ponen sus wakes en el proyecto propio del commander, así que estos son más viejos, o el commander lleva más de los 55 minutos del await sin turno. Los entrega el próximo turno de un commander en ese proyecto, o vx sentinel drain corrido desde él. Mirá Un commander en otro proyecto. |
.claude/settings.json has invalid JSON, leaving it untouched | Arreglá el JSON y volvé a correr vx init para agregar el hook. |
no tasks yet in this project. después de mover el proyecto | La clave de estado sigue a la ruta; ver Estado. |
Landing y strike
| Situación | Qué hacer |
|---|---|
land refused | Tu checkout está sucio, o la branch divergió de la base. Commiteá o hacé stash, o pedile al soldier que haga rebase. Ver Missions en paralelo. Un checkout sucio suele ser solo el scaffold de init sin commitear. |
landed, but automatic strike failed | El merge no se deshace. Corré vx strike <task-id> a mano. |
strike refused | El camp tiene cambios sin commitear o commits sin aterrizar. Aterrizá el trabajo primero. Para una mission enviada con ship, el rechazo dice que mergees el pull request y corras git pull en la branch base, y reintentes. Con gh con sesión iniciada, un PR mergeado cuyo commit de merge está en la base local cuenta como aterrizado. Ver Cómo termina. |
strike refused: ... merge commit is not on <base> yet | El PR mergeó en GitHub pero tu base local todavía no lo tiene. Corré git pull en la branch base y después vx strike de nuevo. |
| El general confirmó que el trabajo del camp ya está en la base o abandonado, y strike igual se niega | vx strike <task-id> --discard hace strike igual e imprime cada commit y cambio que descartó. Solo con la aprobación del general. |
strike refused: scout task ... has no report | El reporte es el producto del scout. Hacé que lo escriba, o pasá --force. |
'gh' is not installed | ship, y aterrizar un PR enviado, necesitan el GitHub CLI. |
vx: tribunal failed at <step>, refusing to push or open a pull request | Falló un paso del tribunal; no se hizo push de nada. Arreglalo en el camp y volvé a hacer ship. |
review blocked: N blocking finding(s) | La revisión adversarial encontró un error o warning (info nunca bloquea). Leé los hallazgos en la salida; arreglalos en el camp, o reintentá con ship --fix para los auto-fix. |
review blocked: incomplete coverage | El revisor no reportó haber leído todos los archivos cambiados. Volvé a hacer ship. |
task ... is running, not interrupted | Solo una tarea interrupted puede re-despacharse. |
Un soldier parece atascado
Mirá vx status. blocked te está esperando: usá decide. unconfirmed o interrupted requieren mirar el camp; ver Blocked e interrupted. Si el commander nunca reporta un soldier que terminó, confirmá que el sentinel corre (~/.vexillum/sentinel.log) y que vx doctor reporta el hook Stop como registrado y encontrando vx ([ok] sentinel Stop hook finds vx).