Troubleshooting

Almost everything can be diagnosed from KumoYami's logs. In the install folder:

docker compose logs -f web      # Ctrl+C to exit
docker compose ps               # container status

The installer is safe to run again: it keeps .env and your data. If it fails, fix whatever the error says and run it again. Its messages are in Spanish; the headings below quote them with a translation.

During installationCopy Anchor Link

«Este instalador necesita permisos de root» (needs root)Copy Anchor Link

Run it with sudo. If you're using environment variables, they go after sudo, not before (exported variables don't make it through):

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» (Linux only)Copy Anchor Link

The installer is Linux only. On Windows and macOS, use Docker Desktop; on a NAS, its guide under By platform.

«Arquitectura no soportada» or «no matching manifest for linux/arm64»Copy Anchor Link

The machine's processor isn't supported by the image. See Raspberry Pi and ARM.

«No hay un terminal disponible para hacer preguntas» (no terminal for questions)Copy Anchor Link

The installer can't ask its questions (for example, when run from a script or a web panel). Use unattended mode with the license details in 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» (the registry rejected the license)Copy Anchor Link

registry.kumoyami.com won't accept the ID or the key. Check that the ID is lic_ followed by 12 characters, and that you're pasting the whole KY1.… key, with no spaces or line breaks. If the details are right, the license may have expired or been revoked: get in touch.

«No se pudo iniciar sesión» or «No se pudieron descargar las imágenes» (couldn't log in / pull)Copy Anchor Link

The server can't reach the registry. Check the internet connection, DNS (getent hosts registry.kumoyami.com) and that the firewall allows outbound HTTPS (port 443).

«El registro no permite descargar la imagen» (the registry won't let you pull)Copy Anchor Link

The saved session is no longer valid (your license key changed) or your license doesn't cover the version you're asking for. Run docker login again with your current key. If your update period has ended, pin your version with KUMOYAMI_VERSION in .env (see Updating).

«Los puertos 80/443 están ocupados» (ports 80/443 in use)Copy Anchor Link

Another program (another Nginx, Apache, another Caddy…) is using those ports and Caddy can't start. Stop that service or, if you want to keep it as your proxy, run the installer with --no-caddy and point that proxy at KumoYami: see Domain and HTTPS. To see what's using them: sudo ss -ltnp | grep -E ':(80|443) '.

DNS doesn't point at this serverCopy Anchor Link

The installer warns you if the domain resolves to a different IP. Fix the A record at your DNS provider; the change can take a while to propagate. If you use Cloudflare's proxy (the orange cloud), the warning is expected and you can ignore it.

«Docker instalado con snap…» (Docker installed with snap)Copy Anchor Link

Docker from snap may not be able to reach the install folder. Use the official Docker (docs.docker.com/engine/install).

After installingCopy Anchor Link

The setup code doesn't show upCopy Anchor Link

KumoYami can take a while to start the first time. Look for it in the logs:

docker compose logs web | grep -i código

If the panel asks for a password instead of the code, the admin is already set up (or there's an ADMIN_PASSWORD in .env): log in with that password.

The site doesn't respond or keeps restartingCopy Anchor Link

Check docker compose logs web. The most common causes:

• Permissions on datos/: it must belong to uid 1000. Fix it with sudo chown -R 1000:1000 datos and docker compose up -d.
• Memory: with less than 1 GB of free RAM, the system may kill the container. Check with free -m.
• Port in use: if another program already uses 4890 on the server, change KumoYami's with KUMOYAMI_PORT in .env.

The HTTPS certificate never arrivesCopy Anchor Link

Caddy needs the domain to point at the server and ports 80 and 443 to be reachable from the internet (the server's firewall, your provider's and, at home, your router). See what it says: docker compose logs caddy.

502 Bad Gateway from the proxyCopy Anchor Link

The proxy can't reach KumoYami. Check the container is running (docker compose ps) and that the proxy points at the right port: 127.0.0.1:4890 from the server itself (or 127.0.0.1:3000 on older installs), or web:3000 from another container on the same Docker network.

Large uploads or WebDAV fail with «413»Copy Anchor Link

That's the proxy's size limit. In Nginx and Nginx Proxy Manager, add client_max_body_size 0; (see Nginx). With Cloudflare, each request is capped at 100 MB on the Free and Pro plans.

LicenseCopy Anchor Link

The panel is lockedCopy Anchor Link

• No contact with the license server for more than 14 days: check the server can reach https://licencias.kumoyami.com. As soon as it does, the license renews itself.
• A version released after your update period: the panel tells you which version to go back to. Pin it with KUMOYAMI_VERSION in .env, or renew your updates.

The public site keeps working either way: only the panel is locked.

It won't activate because it's in use on another serverCopy Anchor Link

Each plan allows a number of servers at once. Deactivate it on the old server (License → Deactivate on this server). If that server no longer exists, get in touch with your license ID. See Moving to another server.

OneDriveCopy Anchor Link

Redirect URI error when connectingCopy Anchor Link

The URI registered in Azure doesn't match the address you're using the panel from. Copy the one KumoYami's form shows and add it in Azure → your app → Authentication. If you use the panel from several addresses (local IP and domain), add one for each.

Azure says creating applications outside a directory is deprecatedCopy Anchor Link

Your personal Microsoft account has no directory. Create a free Azure account with the same email: see Connect OneDrive.

OneDrive stops working after some monthsCopy Anchor Link

The Azure client secret has expired (they last 24 months at most). Create a new one under Certificates & secrets and paste it in by editing the storage in the panel.

AccessCopy Anchor Link

I forgot the panel passwordCopy Anchor Link

Set a new one in ADMIN_PASSWORD in .env and run docker compose up -d. It takes precedence over the panel's.

I lost my second step (2FA)Copy Anchor Link

Add KUMOYAMI_RESET_2FA=1 to .env, run docker compose up -d, log in with just the password, then remove the variable and run docker compose up -d again. See Setup wizard and license.

None of the above?Copy Anchor Link

Get in touch with your license ID (lic_…) and the last lines of docker compose logs web. Never send your full KY1.… key.