Troubleshooting

The most common problems and their fixes. If none fits, ask in the forum or write to support@containly.ch.

The page

The page stays blank or black in the browser

You are opening Containly over plain HTTP while CONTAINLY_SECURE_COOKIES=true is set. The browser then upgrades all assets to HTTPS, which is not served. Set CONTAINLY_SECURE_COOKIES=false in .env, restart with docker compose up -d and reload the page with Ctrl+Shift+R. Use true only behind a reverse proxy with HTTPS.

The installed app (PWA) shows a black screen

The installed app keeps its own shell, but it needs your Containly server for every page; API requests are never cached. If the phone cannot reach the server, the app can stay black: for example you are not in your home network, the VPN is off, or a firewall or the reverse proxy blocks the address. Open the same address in the phone browser: if that does not load either, fix the connection first (connect the VPN, check the firewall and the proxy). If the browser works but the app does not, close the app completely and open it again, or remove it and install it again from the browser.

The setup form does not accept my token

The setup token is printed once in the log (docker compose logs containly) and also stored as /data/setup.token in the containly-data volume. It works only while no admin exists; after the first admin is created, setup mode is closed for good.

Port 8420 is already in use

Change PORT in .env and the ports: mapping in docker-compose.yml to the same free port, then run docker compose up -d.

Licence

"Licence server unreachable"

Containly could not renew the licence. Pro stays active until the date shown on the card and renews on its own once the connection is back. Check that the Containly server can reach containly.ch over HTTPS (outbound firewall, proxy, DNS), then click "Check now" under Settings, Version and licence.

"This licence is already active on another Containly installation"

A licence covers one Containly installation. Deactivate it on the other installation under Settings, Version and licence, or free that installation in your Containly account ("Free for a move"). Then activate it again on this installation. No access to the other installation any more? Write to support@containly.ch.

"That does not look like a licence key" or "This licence key is invalid"

Copy the whole key from the key mail; it starts with CL1-. Keys from the shop need Containly 2.1.0 or newer.

Hosts

"Endpoint limit reached"

The free tier allows 2 endpoints, the local host included. A Pro licence removes the limit.

The agent stays on "Waiting for the agent to connect"

Check the agent logs on the target host. The agent connects out to your Containly address over WSS, so that address must be reachable from the remote host; the one-time token is valid only once.

Backups

Backups fail with "No such image: alpine:latest"

Up to Containly 2.7.3 a backup failed with (HTTP code 404) no such container - No such image: alpine:latest when the helper image had been removed from the Docker host after Containly started, for example by docker image prune -a or a cleanup script. Containly 2.7.4 fixes this: the helper image is pinned to a fixed Alpine version and pulled again automatically when it is missing, so update to 2.7.4 or newer. On an older version, run docker pull alpine:latest on the affected Docker host; the next backup works again without restarting Containly.

The SMB connection test reports a missing sandbox or system call

From Containly 2.5.0 the SMB target runs smbclient in a Landlock sandbox. This needs Linux kernel 6.7 or newer on the machine that runs Containly and Docker's default seccomp profile. Check with uname -r and make sure the Containly container does not run with a custom seccomp profile that blocks the landlock_* system calls. Without the sandbox SMB deliberately stays off; there is no weaker fallback. Other backup targets are not affected. The backup guide lists all requirements.

SMB refuses the connection

Containly accepts only SMB3 with encryption. Enable SMB encryption for the share on the server (on Samba smb encrypt = required, on Windows Server encryption for the share).

Restoring to another host is refused

A restore to another Docker host needs a Pro licence. A stack is also refused when its Compose file is privileged, uses host namespaces, external volumes or bind mounts outside the stack folder. The preview names the reason; see the backup guide.

Lists and users

A list shows only group headers

The list is grouped (see View in the toolbar). Since Containly 2.6.1 every group starts closed; click a header to open it, or choose List under View for the plain list. While a list is grouped, Per page counts groups. The views guide explains all groupings.

Where is "Reset password" for a user?

Open Users and the user's three-dot menu (in the list or at the top of the user detail), then Reset password. It is only offered for local accounts. The user detail shows the role and the sign-in source (Local or Entra) side by side below the name.