Solución de problemas

Empieza aquí cuando algo no funcione. Las primeras secciones son las comprobaciones que sirven para casi todo. Las tablas que vienen después llevan de lo que ves a la página que tiene la solución. La mayoría de esas páginas terminan con su propia sección de solución de problemas; esta página no las repite.

Primeros pasos #

En la máquina del relay, en un terminal:

oar status
oar doctor

oar status dice si el relay responde. Compara sus primeras líneas con la tabla de abajo.
oar doctor muestra la instalación, la configuración y las CLI de proveedores que encuentra. No cambia nada y siempre termina con 0, así que lee las líneas.
Mira el navegador. El punto de estado y los banners indican si el problema está entre el navegador y el relay o detrás del relay.
Lee el registro que corresponde al problema (Registros).
Reinicia lo más pequeño que pueda ayudar (Reiniciar).

Los dos comandos se describen en El comando oar.

Leer `oar status` #

Línea	A qué apunta
`Not set up yet — run: oar setup`	No hay configuración en esta instalación. Ejecuta `oar setup`. Primer arranque
`The relay is running on port <port> (<access>): <url>`	El relay está bien. Abre la URL; `oar url` la muestra con el token. Entonces el problema está en el navegador, el inicio de sesión o una sesión
`The relay is stopped (port <port>, <access>). Start it with: oar start`	Nada responde en el puerto. Ejecuta `oar start` y lee Instalar y arrancar si falla
`Port <port> is held by another program, or by a relay with another token.`	Otro programa usa el puerto, o sigue en marcha un relay antiguo con un token anterior. Consulta Si no arranca
`The relay runs with its earlier settings; restart it to apply the new ones.`	Cambiaste el puerto, el token o el acceso con `oar setup`. Ejecuta `oar restart`
`Service: <state>`	El servicio de arranque al iniciar sesión. Consulta Arrancar al iniciar sesión
`Tunnel: <state>`	El túnel de Cloudflare integrado. Consulta Túnel de Cloudflare

El código de salida 3 significa que el relay no está en marcha, que otra cosa ocupa el puerto o que no hay configuración. El código de salida 0 significa que el relay está en marcha.

Leer `oar doctor` #

Línea	Lo que te dice
`OAR <version>` y `node`	La versión de OAR y el Node.js que ejecuta `oar`. Incluye ambos en un informe
`mode`	git checkout (checkout de git): `oar update` y `oar service` se niegan a funcionar ahí. global install (instalación global) es el caso normal
`state root` y `config`	Qué instalación mira el comando. Dos instalaciones en una máquina tienen dos de cada. `(missing — run: oar setup)` tras la ruta de la configuración significa que no hay configuración; entonces se omiten `port`, `auth token` y `tunnel`
`port`	El puerto y quién puede llegar a él. `localhostOnly: yes` significa solo esta máquina; otros dispositivos necesitan `oar setup --lan` o un túnel
`auth token`	`MISSING` significa que no hay ningún token definido. Ejecuta `oar setup`
`tunnel`	`disabled`, `managed (cloudflared: <path>)` o `managed, cannot start: <reason>`. El motivo nombra lo que falla, por ejemplo que falta `cloudflared`
`database`	La base de datos que usa esta instalación, con su tamaño. `(not created yet)` significa que el relay nunca se ejecutó desde esta instalación. Si faltan tus conversaciones, o los mensajes se quedan pendientes, comprueba que es la base de datos que esperas (Un relay por carpeta de datos)
`provider CLIs`	`gh (Copilot)`, `claude` y `grok` muestran su versión, o `not found`. Doctor busca con el `PATH` de tu terminal; un servicio tiene el `PATH` del momento en que se instaló (Arrancar al iniciar sesión). `cursor` siempre dice `bundled (@cursor/sdk)`, haya o no una clave guardada
`warning`	En WSL, Windows ocupa el puerto del relay. Elige otro con `oar setup --port <port>`

Doctor muestra la carpeta de estado, no la carpeta de registros, y no dice si el relay está en marcha: eso lo hace oar status. Dónde están los registros se explica en Archivos y carpetas.

Registros #

Problema	Lee
El relay no arranca, o se detiene	`server-err.log` en la carpeta de registros, pero solo cuando `oar start` arrancó el propio relay en segundo plano. Con el servicio de Linux los errores de arranque están en el journal (`journalctl --user -u oar`), no en `server-err.log`; consulta Estado y registros
Cualquier cosa que hizo el relay: vistas previas, túneles, actualizaciones, reinicios	`relay-console.log`. Muestra tu token de acceso como `[token]`
Una conversación no responde, o su agente se detiene	`worker-<session>.log`, el worker de esa conversación. El motor de extensión de Copilot no tiene ninguno; consulta `ext-debug.log` y el terminal de Copilot
El servicio no arranca	`systemctl --user status oar`, luego `journalctl --user -u oar`

Todos los archivos de registro, su rotación y la carpeta en un checkout de git están en Archivos y carpetas.

En el navegador #

El punto de estado arriba de la lista de conversaciones: gris es Web relay unreachable (Relay web inaccesible) (el navegador no puede llegar al relay), verde es Web relay reachable (Relay web accesible), ámbar es el relay alcanzado a través de un túnel de Cloudflare conectado. El tooltip dice más, por ejemplo cuántos workers están ocupados. El punto de estado
El banner CLI is offline — messages will queue until it reconnects y CLI offline (CLI sin conexión) en la barra lateral significan que ningún worker de sesión se ha reportado en 10 segundos. En un relay inactivo es normal: envía un mensaje y el banner desaparece. Si se queda, lee el registro del worker. Cuando no se puede llegar al agente

Reiniciar #

Qué	Cuándo	Cómo
El agente de una conversación	Una conversación está atascada, Stop (Detener) no funciona, o el agente debe tomar ajustes nuevos	☠️ Kill session (Matar la sesión) en el menú `⋯`. El historial y la queue se quedan; el siguiente mensaje arranca un worker nuevo. Kill session
El relay	Una versión nueva, una configuración cambiada, una CLI de proveedor recién instalada	`oar restart` en la máquina del relay, o 🌄 Restart web relay (Reiniciar el relay web) en el menú `⋯`. Los dos esperan a los turns en curso, salvo con el servicio de Linux, donde `oar restart` los termina. Reiniciar el relay

Síntomas #

Instalar y arrancar #

Lo que ves	Causa habitual	Solución
`npm install -g @oar-sh/oar` falla con `EACCES`	La carpeta global de npm necesita root	Usa el instalador, no `sudo`. Instalación
Node.js demasiado antiguo o no encontrado; `oar: command not found`; `oar` bloqueado en PowerShell	Node.js anterior a 22.13, o el `PATH` no se ha recargado	Instalación
La instalación falla con errores de node-gyp o prebuild	No hay un `better-sqlite3` precompilado para tu plataforma	Instalación
El relay no arranca tras una instalación con npm 12, con un error de `better-sqlite3`	npm 12 se saltó los scripts de instalación	Reinstala con `--allow-scripts=@oar-sh/oar,better-sqlite3,koffi`, nunca con `--ignore-scripts`. Instalación. El error está en `server-err.log` si `oar start` arrancó el relay, si no en el journal
`Port 3333 is in use by another program ...`	Otro programa o un relay antiguo ocupa el puerto	Si no arranca
`The relay did not come up — see …/server-err.log`	El relay arrancó y terminó	Si no arranca
`Relay already running` o `Relay appears to be owned by another live process`, código de salida 78	Un segundo relay en la misma carpeta de datos	Sigue la indicación del final de la línea (`oar stop, or end process <pid>`). Un relay por carpeta de datos
`[data] Not starting: each database has changes newer than the other's`	Nuevo en 0.9.14 El relay encontró una base de datos anterior en la que se ejecutaba, y las dos contienen trabajo	Quédate con una, mueve los `copilot.db`, `-wal` y `-shm` de la otra a una carpeta tuya, luego `oar start`. Notas de actualización de 0.9.14
`[oar] The relay … is bringing over the database it ran on until now …`	Nuevo en 0.9.14 El primer arranque tras la actualización copia una base de datos grande	Espera; responde en cuanto termina. No arranques un segundo relay. Notas de actualización de 0.9.14
Tras actualizar, han desaparecido las conversaciones de un relay de inicio automático de Windows o de `gh copilot`	Antes de 0.9.14 ese relay guardaba sus datos dentro del paquete	Notas de actualización de 0.9.14
`[startup] Cannot create …` o `… is a file, not a folder`, código de salida 78	Nuevo en 0.9.14 No se puede crear la carpeta de datos o de archivos subidos, por ejemplo porque falta su unidad	Haz que la unidad o la carpeta estén disponibles. Esperar a TEMP y a la unidad de datos
`No systemd user session here`, `Could not enable lingering`, el relay desaparece tras reiniciar la máquina	No hay sesión de usuario de systemd, o lingering está desactivado	Arrancar al iniciar sesión
WSL: el navegador de Windows muestra otra página o rechaza el token	Windows ocupa el puerto	`oar setup --port <port>`. Si no arranca
Con el servicio, las sesiones no encuentran una herramienta o `node`	El servicio conserva el `PATH` del momento en que se instaló	Arrancar al iniciar sesión
`Nothing changed: OAR does not delete or overwrite an autostart entry it did not make.` (Windows)	Nuevo en 0.9.15 Una entrada de Inicio, una tarea de arranque o un lanzador creado o editado a mano se interpone en el cambio	Quítalo tú mismo, o ejecuta el cambio con `--replace`, que guarda una copia. Entradas que OAR no creó
`Nothing changed: the boot task could not be read (…)` (Windows)	Nuevo en 0.9.15 La tarea existe pero OAR no puede leerla, a menudo Access is denied (Acceso denegado) porque guarda la contraseña de otra cuenta	Mírala en el Programador de tareas como administrador. Entradas que OAR no creó
`oar uninstall` se detiene con `Not done: …`	Nuevo en 0.9.15 Falló un paso: el relay no se detuvo, se rechazó una solicitud de administrador, no se pudo eliminar una carpeta	Resuelve la línea anterior y vuelve a ejecutar el mismo comando. `oar uninstall`
Queda una carpeta oculta `.oar-*` junto al paquete eliminado	Nuevo en 0.9.15 Un worker de sesión seguía ejecutándose desde el paquete mientras npm lo eliminaba	Elimina la carpeta cuando esos programas hayan terminado, a más tardar tras reiniciar la máquina. `oar uninstall`

Iniciar sesión y llegar al relay #

Lo que ves	Causa habitual	Solución
Invalid token (Token no válido) en el cuadro de inicio de sesión	Un token antiguo o incorrecto	Usa el token de `oar url`. Si no arranca
Too many failed sign-in attempts. Try again in … seconds. (Demasiados intentos de inicio de sesión fallidos. Vuelve a intentarlo en … segundos.)	Diez tokens incorrectos desde esta dirección en un minuto	Espera a que pase el minuto y luego usa el token correcto. Detrás de un proxy en otra máquina, define `trustProxy`, o todos los visitantes comparten un mismo bloqueo. Protecciones en el inicio de sesión
Un script recibe `401` en direcciones de la API o de archivos que llevan `?token=`	Desde 0.9.11 `?token=` solo inicia sesión en la página	Envía `Authorization: Bearer <token>`. Formas de presentarlo
Todos los dispositivos vuelven a pedir el token	`oar setup --new-token` cierra la sesión en todos los dispositivos	Si pierdes el token
El punto de estado está gris: Web relay unreachable	El relay está detenido, o la dirección es incorrecta	Ejecuta `oar status` en la máquina del relay. El punto de estado
Un teléfono no puede abrir la dirección	El acceso es this machine only (solo esta máquina)	`oar setup --lan`, o un túnel. Desde un teléfono
El túnel está desactivado (`cloudflared is not installed`) o se reconecta una y otra vez	Falta `cloudflared`, el token es incorrecto o falla el inicio de sesión SSH	Túnel de Cloudflare, Túnel SSH
Los mensajes se quedan en cola y la queue está en pausa	El túnel está configurado como `required` y no está conectado	Las mismas dos secciones
Detrás de Caddy o nginx la página se reconecta sin fin, sale en blanco bajo un prefijo, o pide el token una y otra vez	El proxy bloquea los WebSockets, quita un prefijo o necesita más ajustes	Proxy inverso
Detrás de un proxy la página carga pero nada se actualiza en vivo, y el registro del relay dice `Refused a handshake from origin`	El proxy reescribe la cabecera `Host`	Añade el origen público a `allowedOrigins`. `allowedOrigins`

Una conversación no arranca o el agente no responde #

Cada página de proveedor termina con los fallos que puede producir ese proveedor. Una respuesta fallida suele nombrar su causa y a menudo lleva un botón que la soluciona.

Proveedor	Fallos típicos	Solución
GitHub Copilot	Se rechaza guardar SDK con COPILOT_SDK_PATH did not resolve (COPILOT_SDK_PATH no se resolvió), la runtime no pudo autenticarse, no quedan créditos de IA, `oar copilot` dice que falta la CLI de GitHub	GitHub Copilot, Cuando se rechaza guardar SDK
OpenAI	`OpenAI API key is not configured`, falló la detección de modelos, `OpenAI image API failed (401)`	OpenAI
Claude	Falta en New Chat (Nuevo chat), `Not logged in`, una respuesta que apunta a la facturación, Nuevo en 0.9.18 `relay.subscription-key-source`	Claude
Claude API	Nuevo en 0.9.18 La clave está fuera de un workspace (HTTP 400), se ha alcanzado el límite mensual, señalado por `relay.claude-api-cap-reached` o por Start on subscription (Iniciar con la suscripción) en New Chat, la clave no se acepta (`relay.claude-api-key`), el crédito o el límite de gasto de la cuenta (`relay.claude-api-credit`, `relay.claude-api-spend-limit`), la tarjeta muestra `no price known` para un modelo	Claude API, Errores
Claude Cloud	El inicio de sesión caducó, GitHub no está conectado, no hay entorno en la nube	Claude Cloud
Cursor	`Cursor API key is not configured`, `Cursor model "…" is not available`	Cursor
Grok	`Grok CLI was not found on PATH`, `Grok authentication failed`	Grok
DeepSeek	Nuevo en 0.9.17 El saldo se ha agotado (`relay.deepseek-balance`), la clave no se acepta (`relay.deepseek-api-key`), demasiadas solicitudes a la vez (`relay.deepseek-rate-limit`); otros fallos aparecen como `relay.deepseek-…`, por ejemplo `relay.deepseek-api-error`	DeepSeek, Errores

Lo que ves	Causa habitual	Solución
Falta un proveedor en New Chat	Está desactivado, o no tiene clave ni inicio de sesión	La página del proveedor de arriba; Un proveedor desactivado
Set up a provider (Configurar un proveedor) en la primera pantalla	Ningún proveedor está listo	El primer vistazo
La lista de modelos es antigua o incorrecta	La detección tiene que volver a ejecutarse	🤗 Select Models → Refresh (Seleccionar modelos → Actualizar); por proveedor, en su página de arriba
No hay línea de consumo bajo una respuesta	Solo los turns de Copilot registran el consumo del plan	GitHub Copilot
Una tarjeta de Check Usage (Ver consumo) muestra Error, Unavailable (No disponible) o solo estimaciones	Falló la lectura en vivo; la tarjeta recurre a lo que tiene	Actualizar, y lo recientes que son las cifras

Un turn se atasca, falla o vuelve a empezar #

Lo que ves	Causa habitual	Solución
El banner `CLI is offline`	Ningún worker se ha reportado	Cuando no se puede llegar al agente
Un turn largo vuelve a la queue y empieza de nuevo	Se agotó Max turn duration (Duración máxima del turn) (60 minutos por defecto) o la ventana de inactividad (10 minutos)	Sube o vacía Max turn duration en Settings → General (Ajustes → General). Cuando un turn se atasca
`System note: the … runtime sent nothing for Ns ...`	La vigilancia de silencio del motor SDK de Copilot, de Cursor o de Grok terminó el turn	Vuelve a enviar el mensaje. Cuando un turn falla
`Relay timeout after 5 attempts` o `Relay recovery limit reached`	El turn se volvió a poner en cola hasta agotar los intentos	Cuando un turn falla
Una conversación parece bloqueada; Stop no hace nada	El worker está colgado	☠️ Kill session, luego vuelve a enviar el mensaje. Kill session
Los mensajes se quedan pendientes	Hay un reinicio en cola que retiene los mensajes nuevos, u otro relay usa la base de datos	El reinicio espera, Un relay por carpeta de datos
Los mensajes nuevos se quedan en cola y un banner dice Relay restart queued — waiting for N sessions (Reinicio del relay en cola: esperando a N sesiones)	Hay un reinicio en cola que espera a los turns en curso de las sesiones que enlaza; hasta entonces no se entrega ningún mensaje a una sesión	Espera, o pulsa Restart now (Reiniciar ahora) o Cancel restart (Cancelar el reinicio) en el banner. Tras Ask after a queued relay restart has waited (Preguntar cuando un reinicio del relay en cola lleve esperando) (30 minutos por defecto) el banner pregunta en lugar de seguir esperando. El reinicio espera
Los mensajes a una conversación se quedan en cola tras un reinicio del relay	Su worker aún no se ha reconectado. Lo reintenta por sí solo, con un máximo de 8 segundos entre intentos, y desde 0.9.13 también cuando su conexión se cuelga	Su `worker-<session>.log` tiene una línea `worker ws disconnected` por cada intento fallido (los tres primeros, luego una por minuto) que dice por qué. ☠️ Kill session arranca un worker nuevo. Cuando no se puede llegar al agente
Tras un reinicio del relay una sesión se detuvo a mitad de un turn y no hizo nada más	Su turn no se podía volver a ejecutar: el agente ya había recibido el mensaje	Envía un breve «continúa», o activa After a relay restart, tell interrupted sessions to carry on (Tras reiniciar el relay, pedir a las sesiones interrumpidas que continúen) en Settings → General. Una fila relay que dice que el relay se reinició es esa nota. Pedir a una sesión interrumpida que continúe
Un envío falla con This conversation's model "…" is no longer available. Choose a model and send again. (El modelo «…» de esta conversación ya no está disponible. Elige un modelo y vuelve a enviar.)	El envío no nombraba ningún modelo, y el modelo de Copilot fijado en la conversación ha salido del catálogo. Desde 0.9.13 el relay ya no cambia a otro modelo por sí solo	Elige un modelo en el área de redacción y vuelve a enviar. Modelos y razonamiento
Restart web relay o Empty queue (Vaciar la cola) muestra un error	El relay rechazó la solicitud y nombra el motivo, o no respondió	Restart web relay, Empty queue
Una variable definida para el relay no tiene efecto en los agentes	Con tmux solo les llega una lista fija de variables	Qué variables llegan a los agentes
Una respuesta se detuvo con una nota Paused (En pausa)	Un límite de uso	Cuando se alcanza un límite de uso
Un agente en segundo plano o un shell se detuvo solo	Alcanzó el Background task timeout (Tiempo límite de las tareas en segundo plano) (4 horas por defecto)	Tiempo límite de las tareas en segundo plano
Una fila de tarea dice `no output for N min` en ámbar	El comando no ha escrito nada durante más tiempo que Mark a background task as quiet after (Marcar una tarea en segundo plano como silenciosa tras) (10 minutos por defecto)	Abre su consola para ver las últimas líneas. Algunos pasos pasan mucho tiempo en silencio; sube el ajuste, o detén la tarea con Stop si está colgada. Tareas silenciosas
La consola de un comando dice This session did not report an output file for this task. (Esta sesión no indicó ningún archivo de salida para esta tarea.)	Una sesión cuyo agente arrancó antes de la actualización a 0.9.12, o un shell sin Stop en el motor SDK de Copilot	Para el segundo caso, ☠️ Kill session en una sesión inactiva; los comandos siguientes tienen consola. Por proveedor
Una consola dice This task's output is no longer available. (La salida de esta tarea ya no está disponible.)	La tarea terminó hace más de una hora, o se ejecutó antes de la actualización a 0.9.13 y el relay se ha reiniciado desde entonces	Comandos terminados, Tras un reinicio del relay
Una consola se para en Output stops here: this command pipes into tail (La salida se detiene aquí: este comando se canaliza a tail)	Un comando canalizado a `tail` no escribe nada hasta que termina; entonces llega la salida	Para seguir una ejecución así en vivo, haz que registre en un archivo (`> run.log 2>&1`) y sigue ese archivo. Comandos canalizados a tail
Tras un reinicio del relay una consola dice que espera a su worker, sin Stop	El relay conservó la salida del comando, pero solo su worker puede decir si sigue en ejecución	Espera unos segundos. Un comando cuyo worker no volvió se marca como terminado al cabo de un minuto y medio, más o menos. Tras un reinicio del relay
Al volver a una conversación larga no reaparecen todos los mensajes anteriores que habías cargado	Solo se conservan Messages kept per conversation for switching back (Mensajes guardados por conversación para volver) (200 por defecto) alrededor de tu posición, para las últimas ocho conversaciones	Súbelo en Settings → General. Recargar, cambiar, girar
Una conversación no se deja eliminar ni archivar	Todavía corre un turn o una tarea en segundo plano	Eliminar
Una respuesta fallida muestra un botón	El relay conoce la solución	Botones en una respuesta fallida
El relay se detuvo o se reinició, y su registro dice JavaScript heap out of memory	Nuevo en 0.9.19 La memoria del relay llegó a su límite de heap	El relay vuelve a arrancar solo. El relay se quedó sin memoria

Preguntas y aprobaciones #

Lo que ves	Causa habitual	Solución
El agente espera y no pasa nada	Hay una tarjeta de pregunta o de aprobación abierta, quizá en otro dispositivo. Un turn que espera una tarjeta nunca se considera atascado	Responde a la tarjeta, o pulsa Stop. Mientras una tarjeta está abierta
Una tarjeta de aprobación no acepta tu respuesta escrita	El texto escrito no es una forma de decir que sí	Usa Allow (Permitir) o Deny (Denegar). Tarjetas de aprobación
La tarjeta desapareció y el agente siguió	Nadie respondió en 8 horas (2 en el motor de extensión de Copilot), o Stop la cerró	Mientras una tarjeta está abierta
El botón de enviar dice Queue (Poner en cola)	Hay una tarjeta abierta; el mensaje entra después de que respondas	Mientras una tarjeta está abierta
`You are offline. Answer queued`	No había conexión cuando respondiste	Responder desde otro sitio
Un agente de Grok hace una pregunta y no aparece ninguna tarjeta	Grok no tiene tarjetas	Responde en el área de redacción. Grok
Falta un botón de respuesta en una notificación	La pregunta no tiene opciones, o son demasiado largas	Notificaciones

Agentes que trabajan con otras sesiones y relays #

Lo que ves	Causa habitual	Solución
El agente no tiene la herramienta para sesiones, o informa de `REMOTE_RELAY_SESSION_LIMIT`, `REMOTE_RELAY_NESTED_SESSION` o `REMOTE_RELAY_PROVIDER_UNAVAILABLE`	El interruptor está desactivado, o se aplica un límite	Sesiones de agente
`REMOTE_RELAY_LOCKED`	No has mencionado el relay en esta conversación	Relays emparejados
Un relay aparece como Offline (Sin conexión) o Token not accepted (Token no aceptado)	El otro relay está caído, o su token cambió	Relays emparejados
Los agentes de otro relay no pueden enviar prompts aquí (`REMOTE_INBOUND_DISABLED`)	Accept prompts from other relays' agents (Aceptar prompts de agentes de otros relays) está desactivado	Relays emparejados
Vigilar una sesión en un relay emparejado dice que necesita una actualización	El otro relay ejecuta un OAR más antiguo	Sesiones en un relay emparejado
`REMOTE_RELAY_UNKNOWN_MODEL`	El agente nombró un modelo que el relay de destino no lista para el proveedor, por ejemplo `gpt-5-4` en lugar de `gpt-5.4`	La respuesta nombra las coincidencias cercanas y los ids válidos. Qué modelos se aceptan
Un agente que vigila ya no se despierta cuando termina un comando de shell	Desde 0.9.13 los eventos predeterminados omiten los comandos de shell que terminaron bien; los fallos lo siguen despertando	Suscríbete con `task_finished` en `events`. Los eventos predeterminados
Cualquier otro código `REMOTE_…`		Errores

Archivos, vistas previas y compartir #

Lo que ves	Causa habitual	Solución
File not found (Archivo no encontrado) al hacer clic en una ruta de una respuesta	Una ruta absoluta fuera del workspace se lee como ruta del workspace	Adónde lleva un enlace de una respuesta, Lo que puede abrir el visor
Un enlace a un archivo falla o un archivo no se abre	El archivo está fuera de lo que el visor puede leer	Lo que puede abrir el visor
Una carpeta del explorador de archivos se abre vacía	El relay no puede leerla	Límites
El agente debería hacer commit, deshacer o hacer push, pero Git changes (Cambios de Git) no tiene ningún botón	Esa vista solo muestra los cambios	Lo que no hace
Un enlace de vista previa no se abre, muestra `No such preview` o `Preview upstream unreachable`, o la página sale en blanco	La lane está desactivada, el servidor de desarrollo se detuvo, o la app escribe rutas absolutas	Vistas previas
`Preview lane is disabled` o `Preview lane failed its startup checks`	La lane está desactivada o falló una comprobación	Cuando la lane se niega a arrancar
`Too many live previews (max 8)`	El límite	Vistas previas
Un enlace compartido pide al espectador que inicie sesión, muestra un estado antiguo, o nadie más puede abrirlo	Cloudflare Access, una regla de caché, o un relay que solo escucha en esta máquina	Llegar al relay
Un enlace compartido responde `404`	Se dejó de compartir, se renovó el enlace o se eliminó la conversación	Settings → Sharing (Ajustes → Compartir) lista los enlaces que funcionan. Tus enlaces compartidos
Una ruta sigue apareciendo en una vista compartida	Una ruta relativa, o una que está en una imagen	Rutas y nombres de archivo
Una vista previa aparece como no servida en Settings → Previews (Ajustes → Vistas previas)	El relay no pudo comprobarla al arrancar	Se vuelve a comprobar cada 15 segundos. Vistas previas tras un reinicio

Notificaciones y la app instalada #

Lo que ves	Causa habitual	Solución
El interruptor de notificaciones está en gris	La página no está en HTTPS ni en `localhost`	Notificaciones
Las notificaciones dejaron de llegar, o llegan solo a un dispositivo	Bloqueadas en el navegador, un dispositivo desactivado, u otro dispositivo tiene OAR abierto en primer plano	Notificaciones
El navegador no ofrece instalar	El relay no está en HTTPS ni en `localhost`	Lo que necesita
La app muestra Enter your access token to connect (Introduce tu token de acceso para conectarte)	No hay un inicio de sesión válido en la app	Iniciar sesión dentro de la app
Suspend host (Suspender el host) falta o no hace nada	Su ajuste está desactivado, el relay no está en Windows, o algo sigue en ejecución	Suspender el host

Actualizaciones #

Lo que ves	Causa habitual	Solución
Falta Update (Actualizar), o la comprobación no encuentra nada	Un checkout de git, una versión descartada, o no se conoce ninguna versión más reciente	Si no funciona
Check for updates (Buscar actualizaciones) está en gris	`OAR_NO_UPDATE_CHECK` está definida en el relay	Si no funciona
`oar update` termina con 1 y `Could not fetch …` o remite a `--to`	No se puede descargar el manifiesto, o la comprobación está desactivada	`oar update --to X.Y.Z` sigue funcionando. Si no funciona
`oar update --to=0.9.2` instala la versión más reciente	`--to=` se ignora	Escribe `--to 0.9.2` con un espacio. `oar update`
Una actualización falla con `EACCES`	npm no puede escribir en la carpeta del paquete	Si no funciona
La versión antigua sigue en marcha tras una actualización	El reinicio espera a los turns en curso, o la actualización no se aplicó	El reinicio espera, Si no funciona
La app instalada muestra una página antigua	Cambia a la versión nueva cuando arranca	Actualizaciones

El relay se quedó sin memoria Nuevo en 0.9.19 #

El relay arranca con un límite de heap fijo: el 60 % de la RAM de la máquina, en pasos de 64 MB, como mínimo 2.048 MB y como máximo 8.192 MB, y nunca por debajo del valor predeterminado de Node.js, pero nunca por encima de la memoria que hay. En un contenedor con límite de memoria, cuenta ese límite en lugar de la RAM. En una máquina con 4 GB son unos 2,3 GB. Cada inicio escribe en el registro el límite y de dónde viene:

[relay] heap limit 2368 MB (default: 60% of 3.9 GB RAM)

Al arrancar y cada 10 minutos, el registro recibe una línea como [relay] memory rss=812 heapUsed=640 heapLimit=2560, y una línea [relay] memory high: … adicional cuando el heap en uso supera el 80 % del límite.

Cuando el relay se queda sin memoria, vuelve a arrancar solo, como tras cualquier fallo: hasta 2 veces seguidas, y el 3.er fallo seguido lo detiene con el código de salida 1, tras lo cual el servicio de systemd de Linux lo vuelve a iniciar. Una ejecución de 10 minutos o más pone la cuenta a cero. Antes de 0.9.19, un relay que se quedaba sin memoria seguía caído. Tras actualizar desde una versión anterior, el límite de heap y este rearranque solo funcionan cuando el propio oar se ha detenido y vuelto a iniciar (Notas de actualización de 0.9.19).

Para fijar el límite tú mismo, pon heapLimitMb (MB enteros, al menos 512) en config.json y reinicia el relay. Un --max-old-space-size en NODE_OPTIONS, o en la línea de comandos de node que inicia server.js, gana sobre heapLimitMb. A diferencia de heapLimitMb, un NODE_OPTIONS fijado en una shell se pierde cuando otra cosa reinicia el relay.

La instantánea del heap #

Cuando el heap se acerca a su límite, Node.js escribe una instantánea del heap (Heap.<date>.<time>.<pid>.….heapsnapshot) en la carpeta diagnostics de la carpeta de datos del relay (Archivos y carpetas). El relay crea esa carpeta y escribe su ruta en el registro al iniciar; en Linux y macOS solo tú puedes abrirla.

Disco: una instantánea ocupa más o menos lo mismo que el heap en uso, es decir, hasta el límite. Cuando la unidad de la carpeta de datos tiene libre menos del doble del límite de heap, el relay arranca sin instantánea y escribe en el registro por qué.
Memoria: escribirla puede necesitar hasta aproximadamente el doble del heap en uso, y el relay no responde mientras la escribe. En una máquina pequeña, escribirla puede fallar o hacer que el proceso termine; entonces el relay termina como lo habría hecho sin ella.
Leerla: cópiala fuera de la máquina, ábrela en Chrome DevTools, en Memory → Load (Memoria → Cargar), y ordena por Retained size (tamaño retenido) para ver qué retiene la memoria. Una instantánea de una ejecución anterior y sana muestra qué creció.

Una instantánea contiene tus secretos

Una instantánea del heap contiene todo lo que había en la memoria del relay, incluidos el token de acceso y las claves de API de los proveedores. Nunca compartas una tal cual, y bórrala cuando ya la hayas leído: el relay nunca borra instantáneas.

Informar de un problema #

Si nada de lo anterior ayuda, abre una incidencia en github.com/oar-sh/oar/issues. Incluye:

la salida de oar --version;
la salida de oar doctor, y de oar status;
qué hiciste, qué esperabas y qué pasó, con el mensaje exacto;
las líneas relevantes del registro que corresponde al problema (Registros), no el archivo entero.

Quita antes los secretos

Antes de publicar, quita los tokens de acceso (también la parte ?token= de una dirección), las claves de API y los tokens de túnel, y sustituye las rutas personales, los nombres de host y los nombres de cuenta. La incidencia es pública.