Saltar al contenido

Problemas frecuentes

Los errores más habituales al instalar y usar KumoYami, y cómo resolverlos.

Casi todo se diagnostica con los registros de KumoYami. En la carpeta de la instalación:

docker compose logs -f web      # Ctrl+C para salir
docker compose ps               # estado de los contenedores

El instalador se puede repetir sin miedo: conserva el .env y los datos. Si falla, corrige lo que diga el error y vuelve a ejecutarlo.

Durante la instalación

«Este instalador necesita permisos de root»

Ejecútalo con sudo. Si usas variables de entorno, van después de sudo, no antes (las variables exportadas no pasan a través de él):

curl -fsSL https://kumoyami.com/install.sh | sudo KUMOYAMI_LICENSE_ID=lic_xxxxxxxxxxxx KUMOYAMI_LICENSE_KEY='KY1.…' bash

«KumoYami solo se puede instalar en Linux»

El instalador es solo para Linux. En Windows y macOS, usa su propio instalador (Windows y macOS); en un NAS, su guía en Por plataforma.

«Arquitectura no soportada» o «no matching manifest for linux/arm64»

La imagen funciona en procesadores de 64 bits: x86_64 (Intel, AMD) y, desde la versión 0.1.3, ARM (arm64). En un equipo ARM, comprueba con uname -m que el sistema es de 64 bits (debe responder aarch64): los ARM de 32 bits no sirven. Mira Raspberry Pi y ARM.

«No hay un terminal disponible para hacer preguntas»

El instalador no puede preguntar (por ejemplo, al ejecutarlo desde un script o un panel web). Usa el modo desatendido, con lo que necesites en opciones:

curl -fsSL https://kumoyami.com/install.sh | sudo bash -s -- --unattended --domain nube.example.com

«No se ha iniciado sesión en registry.kumoyami.com con esa licencia»

Solo sale si pasas KUMOYAMI_LICENSE_ID y KUMOYAMI_LICENSE_KEY, y no para la instalación: la imagen es pública y se descarga sin iniciar sesión. Si quieres que funcione, comprueba que el identificador es lic_ seguido de 12 caracteres y que la clave KY1.… va entera, sin espacios ni saltos de línea. La licencia se activa en el panel de KumoYami (Licencia).

«No se pudieron descargar las imágenes»

El servidor no llega al registro. Comprueba la conexión a internet, el DNS (getent hosts registry.kumoyami.com) y que el cortafuegos permite HTTPS saliente (puerto 443).

«El registro no ha dejado descargar la imagen»

La imagen es pública y todas las versiones valen para todos los planes: no hace falta iniciar sesión. Si aun así el registro rechaza la descarga, cierra la sesión que tu Docker tenga abierta en él (docker logout registry.kumoyami.com) y vuelve a intentarlo. Si sigue sin dejar, escríbenos con el mensaje completo.

«Los puertos 80/443 están ocupados»

Otro programa (otro Nginx, Apache, otro Caddy…) usa esos puertos y Caddy no puede arrancar. Detén ese servicio o, si quieres mantenerlo como proxy, ejecuta el instalador con --no-caddy y configura ese proxy hacia KumoYami: mira Dominio propio. Para ver quién los ocupa: sudo ss -ltnp | grep -E ':(80|443) '.

El DNS no apunta a este servidor

El instalador avisa si el dominio resuelve a otra IP. Corrige el registro A en tu proveedor de DNS; el cambio puede tardar en propagarse. Si usas el proxy de Cloudflare (nube naranja), el aviso es normal: puedes ignorarlo.

«Docker instalado con snap…»

El Docker de snap puede no tener acceso a la carpeta de instalación. Usa el Docker oficial (docs.docker.com/engine/install).

Después de instalar

No aparece el código de configuración

KumoYami puede tardar en arrancar la primera vez. Míralo en los registros:

docker compose logs web | grep -i código

Si el panel ya pide una contraseña en lugar del código, el administrador ya está configurado (o hay ADMIN_PASSWORD en el .env): entra con esa contraseña.

La web no responde o se reinicia

Revisa docker compose logs web. Las causas más comunes:

  • Permisos de datos/: debe ser del uid 1000. Corrígelo con sudo chown -R 1000:1000 datos y docker compose up -d.
  • Memoria: con menos de 1 GB de RAM libre, el sistema puede cerrar el contenedor. Comprueba con free -m.
  • Puerto ocupado: si otro programa ya usa el 4890 en el servidor, cambia el de KumoYami con KUMOYAMI_PORT en el .env. Si es el 4891 o el 4892, KumoYami arranca sin ese puerto; cámbialo con KUMOYAMI_LIBRARY_PORT o KUMOYAMI_FILES_PORT y publica el mismo número a los dos lados en ports.

El certificado HTTPS no llega

Caddy necesita que el dominio apunte al servidor y que los puertos 80 y 443 lleguen desde internet (cortafuegos del servidor, del proveedor y, en casa, el router). Mira qué dice: docker compose logs caddy.

502 Bad Gateway en el proxy

El proxy no llega a KumoYami. Comprueba que el contenedor está en marcha (docker compose ps) y que el proxy apunta al puerto correcto: 127.0.0.1:4890 desde el propio servidor (o 127.0.0.1:3000 en instalaciones anteriores), o web:4890 desde otro contenedor en la misma red de Docker.

Con el dominio sale el lanzador, el otro módulo o «nada publicado»

KumoYami elige la Biblioteca o Archivos por el puerto al que llega cada petición (4891 y 4892) o por el nombre guardado en Sistema → Módulos. Un dominio sin guardar muestra Archivos; la IP, el nombre del equipo en tu red o una dirección con puerto sin guardar, el lanzador; y un módulo apagado, «nada publicado». Guarda la dirección de cada módulo en Sistema → Módulos: el orden completo, en Cómo elige KumoYami el módulo. Los errores de WebSocket y de certificado, en Dominio propio.

Subidas grandes o WebDAV fallan con «413»

Es el límite de tamaño del proxy. En Nginx y Nginx Proxy Manager, añade client_max_body_size 0; (mira Nginx). Con Cloudflare, cada petición tiene un límite de 100 MB en los planes Free y Pro.

Licencia

El panel está bloqueado

  • Sin conexión con el servidor de licencias durante más de 30 días: comprueba que el servidor puede salir a https://licenses.kumoyami.com. En cuanto lo consiga, se renueva sola.

Mientras tanto la web se detiene para todos y el panel solo muestra cómo resolverlo. No se borra nada.

No se activa porque está en uso en otro servidor

Cada plan admite un número de servidores a la vez. Desactívala en el servidor antiguo (Licencia → Desactivar en este servidor). Si ese servidor ya no existe, escríbenos con tu identificador de licencia. Mira Cambiar de servidor.

OneDrive

Error de URI de redirección al conectar

La URI registrada en Azure no coincide con la dirección desde la que usas el panel. Copia la que muestra el formulario de KumoYami y añádela en Azure → tu app → Autenticación. Si usas el panel desde varias direcciones (IP local y dominio), añade una por cada una.

«La capacidad de crear aplicaciones fuera de un directorio está en desuso»

Tu cuenta personal de Microsoft no tiene directorio. Crea una cuenta gratuita de Azure con el mismo email: mira Conectar OneDrive.

OneDrive deja de funcionar al cabo de meses

El secreto de cliente de Azure ha caducado (duran 24 meses como máximo). Crea uno nuevo en Certificados y secretos y pégalo editando el almacenamiento en el panel.

Acceso

Olvidé la contraseña del panel

Pon una nueva en ADMIN_PASSWORD en el .env y ejecuta docker compose up -d. Manda sobre la del panel.

Perdí el segundo paso (2FA)

Añade KUMOYAMI_RESET_2FA=1 al .env, ejecuta docker compose up -d, entra solo con la contraseña y después quita la variable y vuelve a ejecutar docker compose up -d. Mira El asistente y la licencia.

¿Nada de esto?

Escríbenos con tu identificador de licencia (lic_…) y las últimas líneas de docker compose logs web. Nunca envíes la clave KY1.… completa.

Todas las marcas y logotipos pertenecen a sus respectivos propietarios. Su uso solo indica compatibilidad, no patrocinio ni asociación. El logotipo de Synology es una marca de Synology Inc.; Google Drive, Google Cast y Android son marcas de Google LLC, y el robot de Android es obra de Google, compartida con la licencia Creative Commons Reconocimiento 3.0. Microsoft, Windows y OneDrive son marcas de Microsoft; Amazon S3, de Amazon.com, Inc. o sus filiales; Apple, AirPlay, macOS e iPhone, de Apple Inc.; Raspberry Pi, de Raspberry Pi Ltd; Ubuntu, de Canonical Ltd.; Debian, de Software in the Public Interest, Inc.; Linux, de Linus Torvalds. Este producto usa la API de TMDB, pero TMDB no lo respalda ni certifica.