Resolución de problemas

A continuación se detallan los síntomas, en orden: busque el suyo en la página. Os { NotFound } desde herdr plugin · update indica "not currently on a branch" · tailscale serve failed · no responde (el servicio no inicia) · el teléfono no puede abrir la URL · la página carga pero permanece vacía (página en blanco, 403) · una solicitud de contraseña no acepta la respuesta · no hay notificaciones push · desaparece tras reiniciar el sistema · un panel se queda bloqueado en un ancho reducido · Collie se niega a abrir una ventana de tmux · tmux list: output did not parse · herdr plugin list muestra la versión anterior · interfaz desactualizada tras recompilar.

herdr plugin … falla con Error: Os { code: 2, kind: NotFound, message: "No such file or directory" } (falla la instalación del plugin, falla la invocación de la acción). Esto no es un problema de Collie; significa que el servidor de Herdr no está en ejecución, por lo que su CLI no puede acceder al socket de control (~/.config/herdr/herdr.sock). La señal es el error sin procesar Os {…}: un servidor accesible responde a problemas de ruta/manifiesto con JSON estructurado (p. ej., plugin_manifest_not_found), por lo que un Os { NotFound } simple indica un fallo de conexión al socket antes de examinar Collie o la ruta. Afecta a link, install, action invoke (todos los subcomandos que se comunican con el servidor), mientras que herdr plugin --help sigue funcionando (nunca abre el socket). Solución: inicie Herdr primero (herdr server &, o simplemente abra la TUI de Herdr, que inicia el servidor), confirme que ls ~/.config/herdr/herdr.sock existe ahora e intente la instalación de nuevo. herdr plugin list es una comprobación rápida: si devuelve el mismo error, el servidor está caído.

update falla con You are not currently on a branch. Una instalación de GitHub realizada antes de 0.23.1 (#63): herdr plugin install desacopla en lugar de clonar, por lo que el update antiguo no tenía una rama donde hacer git pull. La corrección se incluye en la copia que repara, por lo que requiere una reinstalación para aplicarse: Si eso falla con "You are not currently on a branch" contiene los tres comandos.

start muestra note: tailscale serve failed. Collie funciona correctamente (sigue activo en 127.0.0.1); únicamente el ingreso a la tailnet no se inició, y el propio error de tailscale figura en el terminal sobre la nota. Causas habituales: el usuario no es el operador de Tailscale (sudo tailscale set --operator=$USER), se cerró la sesión del nodo (tailscale up), o bien (en dominios de tailnet Headscale / .internal) los certificados HTTPS no están disponibles, que es exactamente para lo que sirve COLLIE_SERVE_MODE=http: configúrelo en .env, luego bin/collie restart. Verifique con tailscale serve status.

serve indica HTTPS certificates are not enabled on this tailnet. No se publicó nada y no hay nada en espera. Abra consola de administración, active "Enable HTTPS" y vuelva a ejecutar collie serve. En dominios Headscale / .internal no hay certificados que activar; use COLLIE_SERVE_MODE=http en su lugar.

El banner muestra ⚠ Collie isn't answering on :8787 yet (el servicio no se inicia, conexión rechazada). El servicio se inició pero el servidor HTTP no responde al sondeo. Revise la unidad primero (systemctl --user status collie) y luego bin/collie logs (o journalctl --user -u collie -f para verlo en directo) para identificar la causa: lo más común es que el puerto ya esté ocupado (configure COLLIE_PORT en .env, luego bin/collie restart, que también vuelve a ejecutar tailscale serve contra el nuevo puerto) o que la primera compilación haya fallado (el registro lo indica; corrija y ejecute bin/collie build). La unidad se reinicia automáticamente cada 5 s, por lo que una vez corregida la causa suele recuperarse por sí sola.

El teléfono no puede abrir la URL de la tailnet. Revise la lista en orden: (1) el teléfono ejecuta la aplicación Tailscale y está conectado a la misma tailnet que el host; (2) está abriendo la URL tailnet del banner (bin/collie url), no la de local (http://127.0.0.1:8787 solo funciona en el propio host); (3) MagicDNS está habilitado en la configuración de DNS de su tailnet (la URL es un nombre MagicDNS); (4) el host está en línea: verifique tailscale status en el host o haga ping al host desde la aplicación Tailscale del teléfono; (5) la política de su tailnet realmente admite un par en este nodo (si no lo hace, el banner ahora lo indica debajo de la línea tailnet, y nada más lo hará: el punto de entrada está publicado correctamente, el certificado es válido y curl desde el propio host devuelve 200, porque loopback nunca pasa por el filtro de paquetes). Dos factores hacen que este caso sea especialmente confuso: tailscale ping tiene éxito (los pings de descubrimiento omiten las ACL), y el tráfico bloqueado se descarta en lugar de ser rechazado, por lo que el teléfono simplemente se queda esperando y parece que el servidor está caído. Corríjalo en su política de ACL (<https://login.tailscale.com/admin/acls> en Tailscale; su archivo de política en Headscale). La comprobación es del tipo mejor esfuerzo y deliberadamente prudente: solo advierte cuando el filtro de este nodo admite nada (lo que también puede significar que ningún otro dispositivo se ha unido a la tailnet todavía) y permanece en silencio cuando no puede determinarlo.

La página carga pero se queda vacía (página en blanco, pantalla blanca); Las llamadas a la API fallan 403 cross-origin rejected. Se está accediendo a Collie a través de un origen no esperado: un dominio personalizado o un proxy que reescribe Host. Permita el origen público exacto con COLLIE_ALLOWED_ORIGINS (consulte Configuración), o configure el proxy para que reenvíe Host sin cambios (el cuarto requisito de proxy en docs/deployment.md).

Una solicitud de sudo (o frase de contraseña de SSH, o gpg) no acepta su respuesta. Use Type en la fila Controls, no Send. Send verifica lo que escribió leyéndolo de la pantalla antes de pulsar Enter (#34), y una solicitud de contraseña desactiva el eco, por lo que no hay nada que leer; Type envía las pulsaciones de teclas directamente al panel, Enter incluido. Nada de lo que escriba en Type se almacena, se refleja en un borrador ni se restaura más tarde, y en el momento en que Collie reconoce una solicitud de contraseña también descarta el borrador almacenado (#103).

No llegan notificaciones push. Envíe una manualmente: bin/collie push-test. Tres causas, en el orden en que el comando las distingue: push indica que está deshabilitado (las claves nunca llegaron al puente; ejecute push-keys y reinicie, consulte Web Push); indica que no hay dispositivos suscritos (este teléfono nunca los habilitó en Configuración → notificaciones); o reporta un envío y no llega nada (el teléfono está en un origen HTTP sin cifrar, que no es un contexto seguro; Configuración lo marca como insecure).

Collie desaparece después de reiniciar. En Linux esto casi siempre se debe a la persistencia de sesiones de usuario, por lo que debe ejecutar loginctl enable-linger $USER (Persistencia tras reinicios). En macOS, el agente de launchd se inicia en login, así que verifique que la sesión esté realmente iniciada (no en la ventana de inicio de sesión) y que el agente esté cargado: launchctl print gui/$(id -u)/herdr.collie.

El terminal de un panel está bloqueado en un ancho reducido y una aplicación a pantalla completa en su interior se comprime (Copilot CLI, top, cualquier TUI dibujada en una franja mientras el resto del mirror permanece en blanco). El terminal del panel tiene ese ancho reducido, y Collie lo reproduce fielmente. El ancho de un panel de Herdr proviene de su rectángulo en la cuadrícula de divisiones de la pestaña, por lo que un panel que comparte pestaña recibe una parte de las columnas. Herdr aplica la geometría del panel solo mientras un cliente de escritorio está conectado (herdr#1709): sin nada conectado, cerrar una división deja el panel restante bloqueado en el ancho reducido anterior, y pane.zoom y pane.resize a través del socket tampoco lo modifican. Collie no puede corregir esto desde su lado; no escribe en absoluto la geometría del panel (ADR 0031: el teléfono mueve el terminal del operador solo al pulsar Show in terminal). No hay nada específico de la aplicación: top en un panel de 54 columnas se ve idéntico. Para medirlo, ejecute tput cols en el panel. Ese es el ancho real, y puede no coincidir con lo que informa herdr pane layout. Para solucionarlo, conecte un cliente de Herdr y luego amplíe o redimensione el panel allí (herdr pane zoom <pane-id> --on mueve el terminal una vez que hay algo conectado), o cierre el panel y abra uno nuevo (#167).

Collie se niega a abrir una ventana de tmux (el nueva pestaña del teléfono responde rechazando y especificando window-size). No es un fallo en la solicitud: en versiones de tmux inferiores a 3.7, generar una ventana mientras el window-size del servidor es manual bloquea el servidor completo (tmux #4849, corregido en 3.7), y un servidor bloqueado arrastra consigo a todas las ventanas. Collie lo rechaza y nombra la versión de tmux detectada. La solución es la línea que imprime (tmux set -g window-size latest en ese servidor) o tmux 3.7. Nada más se ve afectado: cualquier otra acción en esos paneles continúa funcionando (Requisitos tiene la misma advertencia).

Collie registra tmux list: output did not parse y el panel se muestra vacío. No es un fallo: algunas versiones de tmux (3.4, no 3.6b) escapan el separador que lee este adaptador al salir de una lista de -F. Collie ahora lee ambos formatos, por lo que una lista que devuelve cero filas se reporta como un error de mux en lugar de almacenarse como un herd vacío; la línea de error indica la versión de tmux y cuántas líneas detectó. Si el problema persiste, anote la versión de tmux -V y abra una incidencia; la corrección corresponde al adaptador, no a su .env.

herdr plugin list muestra la versión anterior después de un update. Comportamiento esperado: Herdr guarda en caché el manifiesto leído durante la instalación o el enlace. La referencia de lo que se está ejecutando es la marca de compilación del pie de página o bin/collie version. Para un clon vinculado, update vuelve a enlazar y se repara de forma automática (fuerce el proceso con herdr plugin link "$(pwd)"); en Herdr ≥0.8.0, el manifiesto se vuelve a leer desde el disco de todos modos.

El teléfono muestra una interfaz desactualizada tras una recompilación. La caché de service-worker de una PWA es por origen, por lo que acceder a Collie desde dos orígenes (un dominio personalizado y la dirección sin procesar de host:8787) genera dos instalaciones, cada una guardando su propio paquete en caché. El pie de página marca de compilación (vX.Y.Z · sha · time) muestra el paquete en ejecución; Collie informa lo que sirve a través del encabezado X-Collie-Build y /api/config. Si no coinciden, el pie de página ofrece "nueva compilación: toque para actualizar." De lo contrario, vuelva a abrir la PWA un par de veces (el SW se actualiza de forma automática) o borre los datos de sitio de ese origen. Práctica recomendada: elegir un único origen HTTPS y mantenerlo. (Sobre HTTP plano el SW no puede registrarse; siempre está actualizado, pero sin funciones de PWA).