Solución de problemas

Busca tu síntoma, lee la causa y sigue la solución. Los ejemplos usan el nombre de contenedor holyarrs; usa el tuyo si es distinto.

Primeras 3 comprobaciones

1. Mira el registro (log): docker logs -f holyarrs. Los secretos salen ocultos. Pulsa Ctrl+C para dejar de seguirlo; el contenedor sigue funcionando.
2. Ejecuta el doctor: docker exec holyarrs /holyarrs doctor. Cada línea dice OK, WARN o FAIL, y cada WARN o FAIL explica cómo arreglarlo.
3. ¿Sigues sin avanzar? Descarga un paquete de soporte y pregunta. Consulta Obtener soporte.

No puedo abrir la página web

Síntoma: el navegador no puede conectar con http://your-server:6262.

Causa: el contenedor está detenido, el puerto no está mapeado o hay un proxy en medio.

Solución:

1. Ejecuta docker ps. Deberías ver holyarrs con 0.0.0.0:6262->6262.
2. Si se reinicia una y otra vez, lee docker logs holyarrs para saber el motivo.
3. Si usas una ruta como /holyarrs, consulta Proxy inverso y URL base.

Permiso denegado

Síntoma: el doctor dice que no se puede escribir en una carpeta, o las importaciones fallan con un error de permisos.

Causa: el propietario de la carpeta en el host no coincide con PUID y PGID.

Solución: ejecuta el chown que sugiere el doctor, o pon en PUID y PGID el propietario de la carpeta. En un NAS, dale a ese usuario lectura y escritura en la pantalla de permisos. Consulta NAS, Synology y Unraid.

No se descarga nada

Síntoma: los títulos siguen faltando y no llega nada a tu gestor de descargas.

Causa: ninguna fuente responde, el gestor de descargas no está conectado o ningún lanzamiento pasa tus Reglas de elección.

Solución:

1. Abre Settings > Downloaders (Ajustes > Gestores de descargas) y haz clic en Test (probar) en tu gestor de descargas. Debería pasar la prueba.
2. Abre Settings > Sources (Ajustes > Fuentes) y haz clic en Test en cada fuente.
3. En el título, abre Choose a release (elegir un lanzamiento) para ver todos los resultados y los motivos por los que no se eligió cada uno.

Consulta Gestores de descargas y Fuentes.

Descargado pero no importado

Síntoma: la descarga terminó en tu gestor de descargas, pero el título no está en tu Biblioteca.

Causa: HolyArrs no ve el archivo en la misma ruta, no puede escribir en la carpeta de la Biblioteca o la importación requiere una decisión.

Solución:

1. Dale a HolyArrs y al gestor de descargas la misma carpeta de descargas en la misma ruta, como /downloads, o rellena Downloader’s path (ruta del gestor de descargas) y HolyArrs’ path (ruta de HolyArrs) en el gestor de descargas.
2. Ejecuta el doctor y arregla cualquier FAIL en las carpetas de descargas o de la Biblioteca.
3. Busca en la lista de descargas los elementos marcados con Needs a decision (requiere una decisión) y aprueba o descarta el plan.

Las importaciones son copias, no hardlinks

Síntoma: el doctor dice que los hardlinks (enlaces duros) no funcionan, o el uso de disco se duplica después de importar.

Causa: las carpetas de descargas y las de la Biblioteca están en discos o montajes distintos.

Solución: monta en el contenedor una sola carpeta superior compartida en lugar de varias separadas. Consulta Carpetas.

HolyArrs no se inicia

Síntoma: el contenedor se detiene o se reinicia enseguida.

Causa: el registro la indica. Las más comunes: /config en una carpeta compartida de red o en una ruta FUSE, o una parte rota.

Solución:

1. Mueve /config a un disco local si el registro lo dice. HolyArrs no ejecuta su base de datos en una carpeta compartida.
2. Si no es eso, inicia en modo seguro, arréglalo desde Settings (Ajustes) y reinicia de forma normal.

Falta una función

Síntoma: una función de la que leíste no está en la app.

Causa: puede que esté retenida en esta versión.

Solución: consulta Funciones retenidas.

Las páginas no tienen nombres ni imágenes

Síntoma: los títulos aparecen sin pósteres ni detalles.

Causa: no se puede llegar al servidor de metadatos.

Solución: revisa tu DNS y tu cortafuegos. La sección Network (red) del doctor muestra si el servidor responde.

Para expertos

Comprobaciones y opciones del doctor

El doctor se ejecuta dentro del contenedor con el mismo usuario que HolyArrs, así que se topa con lo mismo que HolyArrs.

Sección	Muestra
App	Versión, usuario y grupo, umask, si se ejecuta en un contenedor.
Config folder (carpeta de configuración)	Propietario, permisos, espacio libre, si está en un disco local.
Library and download folders (carpetas de la Biblioteca y de descargas)	Si existe, propietario, si se puede escribir, espacio libre, hardlinks entre las carpetas de descargas y las de la Biblioteca.
Network (red)	Si el nombre del servidor de metadatos se resuelve y si responde.
Clock (reloj)	Hora, zona horaria (TZ), una advertencia cuando el reloj está claramente mal.

Opción	Qué hace
-config <folder>	Comprueba otra carpeta de configuración de HolyArrs en lugar de /config.
-json	Muestra el informe en JSON.

El código de salida 0 significa que nada falló; 1 significa que alguna línea dice FAIL. El informe nunca muestra claves, contraseñas ni tokens. Solo lee, salvo un pequeño archivo de prueba que escribe y borra. Si se inicia como root, también entrega la carpeta de configuración a PUID:PGID, como en un inicio normal.

Si HolyArrs se reinicia una y otra vez, docker exec falla. Ejecuta el doctor en un contenedor nuevo con las mismas carpetas:

docker run --rm --volumes-from holyarrs -e PUID=<puid> -e PGID=<pgid> -e TZ=<tz> holyarrs/holyarrs:<tag> doctor

Con Compose: docker compose run --rm holyarrs doctor.

Comprobación de carpetas al iniciar

Al iniciar, HolyArrs comprueba sus carpetas y escribe en el registro una línea de resumen, como folders: 4 ok, 1 not writable, y después una línea por cada carpeta con problemas, con su solución. La comprobación se detiene a los 3 segundos para que el inicio nunca se quede colgado. Una carpeta demasiado lenta en responder cuenta como no comprobada; suele ser un disco que sale del reposo o una carpeta compartida de red lenta. El doctor la comprueba sin el límite de tiempo. Consulta Registros.

La imagen no tiene shell

La imagen solo contiene el programa de HolyArrs, así que sigue siendo pequeña y deja menos a un atacante. docker exec holyarrs sh falla a propósito. Para mirar más de cerca, inicia a su lado un contenedor auxiliar de usar y tirar:

docker run --rm -it --pid container:holyarrs --network container:holyarrs --volumes-from holyarrs busybox sh

Ve el proceso de HolyArrs, comparte su red y tiene las mismas carpetas en las mismas rutas. Se ejecuta como root, así que mira pero no cambies nada: un archivo escrito como root puede quedar ilegible para HolyArrs. Para probar como el usuario de HolyArrs, añade --user <PUID>:<PGID>.

Averiguar la versión

docker inspect --format '{{ index .Config.Labels "org.opencontainers.image.version" }}' holyarrs

La sección App del doctor muestra lo mismo.

Relacionado

• Obtener soporte
• Registros
• Comprobaciones de salud