# Troubleshooting > Diagnosing a failed or partial ScanSuite installation, and removing one. Source: https://scansuite.eu/documentation/installation/troubleshooting Last reviewed: 2026-10-19 Find out what is wrong with a ScanSuite server and fix it: run `doctor`, look its message up in the tables below, apply the fix, and run `doctor` again until it ends with `No problems found`. For the cloud installs, see the *Common messages* of [Install on Google Cloud](https://scansuite.eu/documentation/installation/install-on-google-cloud) and [Install on Microsoft Azure](https://scansuite.eu/documentation/installation/install-on-azure); for DefectDojo, [Set up DefectDojo](https://scansuite.eu/documentation/installation/set-up-defectdojo). ## Ask the installation what is wrong ```bash cd /opt/scansuite && ./scansuite doctor ``` `doctor` checks the host (Docker, free disk space, ports 80 and 443, the clock), the installation (`.env`, the licence, the TLS certificate, the database password) and the services (which ones are not running, Redis, the database migration, whether nginx serves the sign-in page), then shows the recent errors from the logs. It reports every check rather than stopping at the first failure, and ends with `[+] No problems found` or `[-] N problem(s) found` (exit code 1). Lines starting `[-]` are problems, `[!]` warnings. *A healthy installation (abridged)* ``` [*] Host [+] docker 27.3.1 with the compose plugin [+] 84G free for docker images [+] 41G free in /var/tmp for scans and logs [+] port 80 is served by this installation [+] port 443 is served by this installation [+] clock check skipped (no NTP server configured) [*] Installation [+] .env is complete [+] licence acme_a1b2c3.lic [+] the PoC worker can read the licence [+] TLS certificate valid for 364 more days [+] the database accepts scansuite with the password in .env [*] Services [+] 10 service container(s) running [+] Redis saves its snapshots [+] the database migration job completed [+] nginx serves the application (HTTP 200) [+] No problems found ``` > **Agent prompt: Ask an assistant to read the report** > > ```text > Here is the output of ./scansuite doctor from my ScanSuite server, and the troubleshooting page https://scansuite.eu/documentation/installation/troubleshooting. Tell me what is wrong and the exact commands to fix it, most likely cause first. Mark any command that deletes data, and do not run it. > ``` Check the output for host names, user names or tokens before you paste it anywhere: the *Recent errors in the logs* block repeats raw log lines. Send the same output, with that of `./scansuite version`, with any support request. ## What doctor reports, and the fix ### Host | Message | Meaning | Fix | |---|---|---| | docker is not installed | Docker is missing. | Install Docker and its Compose plugin ([Technical Requirements](https://scansuite.eu/documentation/installation/technical-requirements)), or run ./scansuite install again, which installs it on Ubuntu, CentOS, Debian and Kali. | | docker … has no compose plugin (docker-compose-plugin) | Docker is there, Compose is not. | Install the docker-compose-plugin package. | | only NG free where docker stores images (20G recommended) | The disk with /var/lib/docker is filling up. | Remove images nothing uses (docker image prune), or grow the disk. | | only NG free in /var/tmp, where scans and the log file are written (10G recommended) | Scans may fail, and Redis and the database may stop saving. | Free space in /var/tmp, or grow the disk. | | port 80 (or 443) is held by (pid N), so this installation's nginx cannot start | Another program has the port; the console is unreachable. | Stop that program and run ./scansuite restart, or let it proxy to ScanSuite ([SSL/TLS Setup](https://scansuite.eu/documentation/installation/ssl-tls-setup)). | | the host's own nginx service is enabled: it takes ports 80 and 443 at every boot … | It works now but will fail after a reboot. | sudo systemctl disable --now nginx (or the service named), or use the proxy route. | | NTP server is not reachable / answers ping but not NTP on udp/123 | The time server set in NTP_SERVER cannot be used. | Open udp/123 to it, or correct NTP_SERVER in .env. | ### Installation | Message | Meaning | Fix | |---|---|---| | no .env (run ./scansuite install ) / SCANSUITE_TAG is not set in .env | The installation was never completed. | ./scansuite install | | .env is not mode 600 | Other accounts on the host can read the passwords in it. | chmod 600 /opt/scansuite/.env | | REDIS_PASSWORD (or PS_DATABASE_PASSWORD) in .env is still a placeholder | A generated password is missing. | Run ./scansuite install again; it fills it in. | | no licence file in /opt/scansuite/key/ (_.lic) | The licence is missing. | Copy your licence file into /opt/scansuite/key/. | | the licence in this release expired on | Nothing starts with an expired licence. | Ask for a renewed licence, copy it into key/ (remove the old one) and run ./scansuite update. | | the licence expires on (in N days) | A warning. | Arrange the renewal in time. | | the PoC worker (uid N) cannot read key/*.lic and will not start … | The proof-of-concept sandbox cannot start. | ./scansuite restart | | no TLS certificate at services/nginx/certs/cert.pem | nginx has no certificate. | Put a certificate and its key there ([SSL/TLS Setup](https://scansuite.eu/documentation/installation/ssl-tls-setup)). | | services/nginx/certs/key.pem is not the private key of cert.pem … | The two files do not belong together; nginx will not start. | Copy the key that belongs to the certificate, then docker compose restart nginx. | | the TLS certificate expired N days ago | Browsers refuse the console. | Renew it ([SSL/TLS Setup](https://scansuite.eu/documentation/installation/ssl-tls-setup)). | | the database refuses scansuite with PS_DATABASE_PASSWORD from .env … | The password in .env and the database differ. | ./scansuite restart sets it. | ### Services | Message | Meaning | Fix | |---|---|---| | ScanSuite Teams is not running. Start it with ./scansuite start | Nothing is running. | ./scansuite start | | Services needing attention: | That service exited, is unhealthy, keeps restarting or never started. | ./scansuite logs shows why; then ./scansuite restart. | | Redis could not save its last snapshot … | The disk or memory is full. | Free disk space and memory, then ./scansuite logs redis. | | The database migration job failed (exit N); web and the workers wait for it. | The database could not be brought up to date, so nothing else starts. The next line names the cause. | See the next table. | | nginx answered 502: it cannot reach web … | nginx lost track of the web service. | ./scansuite restart | | nginx did not answer on https://127.0.0.1/ | nginx is not serving. | ./scansuite logs nginx; check the ports. | | this installation's nginx runs but its ports are not published … | Another program held ports 80 and 443 when nginx started. | Free the ports, then ./scansuite restart --hard. | The web, worker and scheduler services restart by themselves after a crash. One that crashes again and again shows `Restarting` in `./scansuite status`; its log says why. ### When the database migration fails | Cause doctor prints | Meaning | Fix | |---|---|---| | This database was created by a build whose schema history this release does not contain. | The database comes from a build this release cannot upgrade. | Restore a backup made by a compatible release, or start over with an empty database (below). | | PS_DATABASE_PASSWORD in .env is not the password the database was created with. | .env was replaced or edited. | Put the earlier .env back (an update keeps a copy as .env.bak-, or restore your secrets backup), then ./scansuite restart. | | The licence in key/ was not accepted by this release. | The licence does not match the release images. | Check that the licence code is the one the release was installed with (./scansuite version). | Its full log: `./scansuite logs migrate`. > **A person does this step:** Starting over with an empty database deletes every scan, finding and setting. Only a person decides it and answers the question it asks; back up first, as in Remove ScanSuite from a host below. ```bash cd /opt/scansuite && ./scansuite reset db ``` It asks `Delete the ScanSuite Teams database? [y/N]`, removes the database, starts with an empty one and prints the setup-page hint: create the first account again. ## Messages from install and update | Message | Meaning | Fix | |---|---|---| | Registry sign-in failed. Check the credentials sent with your licence. | The token was wrong, or there was no terminal to type it in. | Start the installer again in a terminal a person can type into, and type the token at its Password: prompt. | | could not pull appsec4u/teams-web: -- is the licence code correct? | No images for that code. | Check the code against the licence file name. | | TLS handshake timeout, again and again | A firewall lets the registry through but not the layer downloads. | Allow both production.*.docker.com hosts ([Technical Requirements](https://scansuite.eu/documentation/installation/technical-requirements)). One timeout is passing trouble: run the command again. SCANSUITE_PULL_ATTEMPTS= sets the retries per image (default 4). | | No docker installer for this distribution. | The installer cannot install Docker here. | Install Docker and its Compose plugin yourself, then run the installer again. | | Docker installed. Run 'newgrp docker' (or log out and back in) … | Your account was added to the docker group. | newgrp docker, or sign in again. | | cannot read …/services/nginx/certs/key.pem, so the update could not keep it. Nothing was changed. | The key was copied in with sudo and belongs to root. | Run the sudo chown command the message prints, then the update again. | | This release changed the same lines this host had changed in: | Your change to a configuration file could not be merged. | The release's file is in place; yours and the change alone (.patch) are in .replaced-/. Apply it again by hand, or move it to docker-compose.local.yml. | | These release files differed here and were replaced: | A file that is not configuration was changed on the host. | Nothing to do; copies are in .replaced-/. | | nginx could not take ports 80 and 443: another program holds them | Everything but nginx is running. | Free the ports, then ./scansuite restart; or use the proxy route. | | DefectDojo did not start; try again with: ./scansuite dojo start | Usually ports 8080 or 8443 are taken. | Free them or move DefectDojo ([Set up DefectDojo](https://scansuite.eu/documentation/installation/set-up-defectdojo)), then ./scansuite dojo start. | | Some services did not become healthy within 5 minutes. | A service did not come up. | ./scansuite doctor | | Could not reach the release repository. | No network to github.com. | Check the network and run the update again; .env is saved as .env.bak-. | ## Commands for diagnosis Run them in `/opt/scansuite` as the account that installed ScanSuite. | Command | What it shows or does | |---|---| | ./scansuite status | The containers, and the ones needing attention. | | ./scansuite logs [] | The last 200 log lines of one service, or of all. Options after the name go to docker compose logs: ./scansuite logs web -f follows the log. | | ./scansuite version | The release, licence and images installed, and the images actually running — which differ if the host was not restarted since an update. | | ./scansuite restart | Brings every service back, waiting until each is healthy, and says which one is not. | | ./scansuite restart --hard [] | Recreates every container. It interrupts running scans. n sets the number of scan workers. | | ./scansuite dojo start | Starts DefectDojo on its own. | | cat /var/tmp/scansuite.log | The application log (LOG_FILE in .env). | | systemctl status scansuite | The boot service that starts ScanSuite with the host. | | sudo systemctl restart docker | Restarts Docker itself, when containers do not start at all. | The services you can name in `logs`: `nginx`, `web`, `worker`, `worker_admin`, `celery_beat`, `worker_poc`, `migrate`, `postgres`, `redis` and `seaweedfs`. What each does, and every command and setting, are in [Setup parameters and services](https://scansuite.eu/documentation/administration/setup-parameters-and-services). ## Remove ScanSuite from a host To take ScanSuite off a host, or to reinstall from scratch. Back up first if the data may be needed again — the database cannot be opened without `.env` and `key/`: ```bash cd /opt/scansuite ./scansuite backup secrets /path/outside/the/host # prints its password once: note it ./scansuite backup db /path/outside/the/host ``` See [Backup and restore](https://scansuite.eu/documentation/administration/backup-and-restore). > **A person does this step:** The purge below deletes the database and the stored files and cannot be undone. A person decides it and answers the Continue? [y/N] question. ```bash cd /opt/scansuite && ./scansuite uninstall --purge ``` Without `--purge` it only stops ScanSuite and removes the boot service, keeping the data. Expected: `ScanSuite Teams stopped and removed from boot`. DefectDojo is a separate installation and keeps running; remove it, with its data, from its own folder: ```bash cd /opt/scansuite/defectdojo && docker compose down -v ``` The images and the installation folder stay on the host. Remove them to free the space; the folder needs sudo because the services write some of its files as root: ```bash docker images -q 'appsec4u/*' | sort -u | xargs -r docker rmi -f docker rmi nginx redis:6-alpine postgres:13-alpine sudo rm -rf /opt/scansuite ``` DefectDojo's own `postgres` and `redis` images remain; `docker images` lists them. On a host that runs nothing else, `docker image prune -a` removes every image no container uses.