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

Mail

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