Troubleshooting
Start here
- Read the installer's message. When the installer stops, it says why in one line and names its log.
Run the doctor. It checks the machine and the installation and changes nothing:
sh install.sh --doctorSend a support bundle. One file with the doctor's report, logs and configuration, with secrets removed:
sh install.sh --collect-logsIt is written to
~/.cerberon/collect-logs-<time>.tar. Send it to Cerberon support.
Locked out (forgotten administrator password)
Cerberon has no password-reset email or link: anyone who could reach such a link could take the instance over. Instead, whoever controls the machine resets the password there. On the machine (on Windows, first open Ubuntu with wsl -d Ubuntu-24.04):
docker exec -it cerberon-core bun /app/packages/core/src/reset-password.js --user <account name>It asks for the new password (10 or more characters, hidden as you type), signs that account out everywhere, and records the change in the audit log. If you do not know the account name, run it with any name: it changes nothing and lists the accounts that exist.
Logs
| Log | Where |
|---|---|
| Installer (Linux, and the Cerberon part on Windows) | ~/.cerberon/logs/install-<time>.log (newest ten kept) |
| Windows installer and start-up task | C:\ProgramData\Cerberon\install-windows.log |
| Cerberon itself | cd ~/.cerberon && docker compose logs core |
| In-app updates | ~/.cerberon/updates/ |
Run the installer with --verbose to see every detail on screen.
Installation
| Message | What to do |
|---|---|
| "a licence key is required" | Run the installer in a terminal so it can ask, or set CERBERON_LICENSE_KEY. |
| "this licence is already active on another machine" | The key is in use elsewhere. Contact Cerberon to release it (licence). |
| "port 443 is already in use" | Another program (often a web server) uses the port. Stop it, or choose another port yourself with CERBERON_PORT=<port>; the installer never picks one on its own. |
| "OpenSSL 3.0 or newer is required" | Use a supported Linux release (requirements). |
| "this host runs Podman" / "rootless Docker" | Cerberon needs Docker Engine running as the system service. |
| "this user cannot reach the docker socket" | Add your account to the docker group (the installer offers to), then log out and back in. |
| "Docker Engine is required and was not found" | Install Docker Engine, or run the installer in a terminal on Ubuntu, Debian, RHEL, Rocky or AlmaLinux so it can offer to. |
| "the tools build needs about 16 GB free" | Free disk space where Docker keeps images (docker system prune removes unused images), then run the installer again. |
| "cannot reach …" during the machine check | That outbound address is blocked; the message says what is affected. Allow it, or set your proxy (requirements). |
| "the snapshot is not a readable copy" | The pre-update copy failed its check; nothing was changed. Check free disk space and run the update again. |
Windows
| What you see | What to do |
|---|---|
| "run PowerShell as Administrator" | Right-click PowerShell, Run as administrator, and run the command again. |
| "Windows needs a restart to turn on WSL" | Normal the first time. Restart and run the same command again. |
| "virtualisation is turned off in this PC's firmware" | Turn on Intel VT-x or AMD-V in the BIOS/UEFI setup, then run the command again. |
| "is a Windows Server" | Windows Server is not supported; install on Linux. |
| Other machines cannot connect | Mark the network Private: Set-NetConnectionProfile -InterfaceAlias "<network>" -NetworkCategory Private. Check the "Cerberon" task is running in Task Scheduler. |
| Cerberon does not answer after a restart | Wait two minutes for the start-up task. Then check C:\ProgramData\Cerberon\install-windows.log for a "keep-running" line. |
Scans
| Message | What to do |
|---|---|
| "an update … is in progress; new scans are paused" | Wait for the update to finish; scheduled scans run afterwards by themselves. |
| A scan is refused for memory, disk or CPU | The machine is too busy for that scan. Wait for running scans to finish, or add resources. |
| "the tools image … is not loaded" | The scanner tools are missing. Run sh install.sh --tools. |
| "no AI provider is configured" | Agent-assisted scans need Settings → AI (configuration). |
| A scan shows interrupted | Cerberon or the machine restarted while it ran. Start it again. |
| Mobile scans report the analyser not ready | The mobile analyser is still starting; wait a minute, or run sh install.sh --repair. |
Repair
sh install.sh --repair re-runs the safe steps (scanner tools, templates, the mobile analyser's key, folder permissions) without changing your settings or data.
sh install.sh --renew-cert issues a new Cerberon certificate (when you use Cerberon's own) and restarts Cerberon.