Troubleshooting

Start with sudo /opt/tadbir/current/compose/onprem/doctor.sh: its summary answers most questions, and its archive is what Oloom support needs. See Information for support.

Installation and upgrades

Symptom	Cause	Fix
checksum mismatch or signature check failed	The bundle is incomplete or modified.	Copy it again and compare sha256sum with Oloom's checksum.
set DOMAIN and TADBIR_BOOTSTRAP_ADMIN_EMAIL	First run: settings file just created.	Fill both values in /opt/tadbir/.env, run again.
offline maps missing	No map pack given.	Run the installer with --geo <map pack>.
Docker 24 or newer required, at least 8 GB RAM, at least 20 GB free	Server below requirements.	Upgrade Docker, add memory or disk.
version X is installed; use upgrade.sh	The installer was run with a newer bundle.	Use upgrade.sh from that bundle.
services did not become healthy	A container did not start.	compose.sh ps, then compose.sh logs <container> for the one not healthy.
Upgrade refused: after your maintenance end	Your maintenance does not cover this version.	Renew with Oloom, upload the new license, run upgrade.sh again.
not enough disk for the pre-upgrade snapshot	Not enough space to copy the database.	Free space (see Disk space).
Port 80 or 443 already in use when starting	Another web server runs on the machine.	Stop it, or install Tadbir on a dedicated server.

Sign-in and browser

Symptom	Cause	Fix
Browser warns the connection is not private	Self-signed or untrusted certificate.	Install the certificate (or your company CA) as trusted on each device.
Page not found / cannot connect	The hostname does not resolve to the server.	Fix the internal DNS record or hosts file for DOMAIN.
Sign-in page loops back, or "invalid redirect"	Users open Tadbir with another name or IP than DOMAIN.	Always use https://<DOMAIN>. To change the name, change DOMAIN and the certificate, then restart.
First administrator cannot sign in with the temporary password	It was already changed at first sign-in.	Use the password chosen then. If it is lost, use "Forgot password" on the sign-in page (needs email) or contact Oloom support.

License and modules

Symptom	Cause	Fix
Modules missing, banner "No license is installed"	No license uploaded.	Upload it.
Banner "license has expired or is invalid"	Term over or file invalid.	Upload a renewed file.
Banner "released after your maintenance period ended"	A version newer than your maintenance is installed.	Renew, or rollback.sh --yes (see Upgrades).
Banner "server clock has moved backwards"	Clock went back more than 24 hours.	Correct the server time; modules come back by themselves.

Email

Symptom	Cause	Fix
Invitations or password-reset emails never arrive	No mail server, or no network route to it.	Set KC_SMTP_* and the mail network, see Email.
Email errors in compose.sh logs keycloak	Wrong login, port, or the server refuses STARTTLS.	Check the KC_SMTP_* values with your mail administrator.

Maps and addresses

Symptom	Cause	Fix
Map background is blank, or address search finds nothing	The address is outside the countries of your map pack.	Place the site with a pin on the map (coordinates are kept). Ask Oloom for a pack with more countries.
No map at all after install	The map pack was not unpacked correctly.	Check DATA_ROOT/geo/photon/photon.jar and DATA_ROOT/geo/tiles/tiles.mbtiles exist; run the installer again with --geo.