Knowledge base / Operation
Troubleshooting
Typical faults, their cause and what helps.
The first look always goes to the containers and the log:
docker compose ps
docker compose logs --tail 100 contracthub
Quick diagnosis
| Symptom | Probable cause | Remedy |
|---|---|---|
| Page not reachable | Reverse proxy not running, DNS or firewall | Check the proxy and name resolution |
| “Bad Gateway” (502) | Container not running, or the proxy cannot reach port 3000 | docker compose ps, look at the log |
| Start aborts with a message about a variable | A value in contracthub.env is missing or invalid |
The message names the variable. Correct it, then docker compose up -d --force-recreate contracthub |
| Start aborts with a database error | Database not ready yet, or wrong password in DATABASE_URL |
docker compose logs contracthub-db, compare the password with postgres.env |
| Maintenance page (503) for everyone | A restore is running | Wait; the progress is in the log |
| Notice “New version available” stays | The browser holds the old version | User menu → Clear cache and reload |
| Lock screen “License” | Trial or license expired | Install the license |
Sign-in
| Message | Cause | Remedy |
|---|---|---|
| “Your account has no Kontris role” | The user has none of the three roles at the provider | Assign a role, sign in again |
Microsoft reports AADSTS50011 |
Redirect URI does not match APP_BASE_URL |
Enter exactly https://<address>/auth/callback in Entra |
Microsoft reports AADSTS700027 or invalid_client |
Secret or certificate expired | Renew it, see Entra ID |
| Sign-in hangs after the redirect | The server cannot reach the provider | Check the outgoing firewall; use a local account meanwhile |
| Signed out again right after signing in | APP_BASE_URL does not match the address in the browser, or TRUST_PROXY is missing |
Check both values, see HTTPS |
| Local account locked | Too many failed attempts | Wait 15 minutes, or an admin resets the password |
Lost admin password:
docker compose exec contracthub node dist/reset-admin-password.js
Failed mails are listed with the mail server’s message under Administration → Notifications. The most common causes are under Setting up mail.
Documents
Message “File missing” when opening a document:
docker compose exec contracthub node dist/storage.js check
ls -ln /opt/contracthub/files
The folder files must belong to UID and GID 1000.
Disk space
A full disk is the most common cause of trouble with the containers themselves. Check df -h and df -i. Images, database, documents and backups need space, and during a backup temporarily also the size of the database dump.
Information for support
When you contact us, please include this output, but no passwords and no .env files:
docker compose ps
docker images | grep contracthub
docker compose logs --since 2h contracthub > contracthub.log 2>&1
curl -s http://127.0.0.1:3000/api/version
The logs contain no passwords or keys; Kontris redacts them.
As of 2026-11-15 · Stuck? Write to us