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 contenedoresEl 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 Docker Desktop; en un NAS, su guía en Por plataforma.
«Arquitectura no soportada» o «no matching manifest for linux/arm64»
El equipo no tiene un procesador compatible con la imagen. 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 los datos de la licencia en variables:
curl -fsSL https://kumoyami.com/install.sh | sudo KUMOYAMI_LICENSE_ID=lic_xxxxxxxxxxxx \
KUMOYAMI_LICENSE_KEY='KY1.…' bash -s -- --unattended --domain nube.example.com«El registro ha rechazado la licencia»
registry.kumoyami.com no acepta el identificador o la clave. Comprueba que el identificador es lic_ seguido de 12
caracteres, y que pegas la clave KY1.… entera, sin espacios ni saltos de línea. Si los datos son correctos, la
licencia puede estar caducada o revocada: escríbenos.
«No se pudo iniciar sesión» o «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 permite descargar la imagen»
La sesión guardada ya no vale (cambió la clave de la licencia) o la licencia no cubre la versión que pides. Repite el
docker login con la clave actual. Si tu periodo de actualizaciones terminó, fija tu versión con KUMOYAMI_VERSION
en el .env (mira Actualizar).
«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 y HTTPS. 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ódigoSi 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 consudo chown -R 1000:1000 datosydocker 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_PORTen el.env.
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:3000
desde otro contenedor en la misma red de Docker.
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 14 días: comprueba que el servidor puede salir a
https://licencias.kumoyami.com. En cuanto lo consiga, se renueva sola. - Versión posterior a tu periodo de actualizaciones: el panel te dice a qué versión volver. Fíjala con
KUMOYAMI_VERSIONen el.env, o renueva las actualizaciones.
La web pública sigue funcionando en ambos casos: solo se bloquea el panel.
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.