Wissen / Betrieb
Fehlerbehebung
Typische Störungen, ihre Ursache und was hilft.
Der erste Blick gilt immer den Containern und dem Log:
docker compose ps
docker compose logs --tail 100 contracthub
Schnelldiagnose
| Symptom | Wahrscheinliche Ursache | Abhilfe |
|---|---|---|
| Seite nicht erreichbar | Reverse Proxy läuft nicht, DNS oder Firewall | Proxy und Namensauflösung prüfen |
| „Bad Gateway“ (502) | Container läuft nicht oder der Proxy erreicht Port 3000 nicht | docker compose ps, Log ansehen |
| Start bricht mit einer Meldung zu einer Variable ab | Wert in contracthub.env fehlt oder ist ungültig |
Die Meldung nennt die Variable. Korrigieren, dann docker compose up -d --force-recreate contracthub |
| Start bricht mit einem Datenbankfehler ab | Datenbank noch nicht bereit oder falsches Passwort in DATABASE_URL |
docker compose logs contracthub-db, Passwort mit postgres.env vergleichen |
| Wartungsseite (503) für alle | Eine Wiederherstellung läuft | Abwarten, der Fortschritt steht im Log |
| Hinweis „Neue Version verfügbar“ bleibt | Der Browser hält die alte Version | Benutzermenü → Cache leeren und neu laden |
| Sperrbildschirm „Lizenz“ | Testphase oder Lizenz abgelaufen | Lizenz einspielen |
Anmeldung
| Meldung | Ursache | Abhilfe |
|---|---|---|
| „Dein Konto hat keine Kontris-Rolle“ | Der Benutzer hat beim Anbieter keine der drei Rollen | Rolle zuweisen, neu anmelden |
Microsoft meldet AADSTS50011 |
Redirect URI passt nicht zu APP_BASE_URL |
In Entra genau https://<adresse>/auth/callback eintragen |
Microsoft meldet AADSTS700027 oder invalid_client |
Secret oder Zertifikat abgelaufen | Erneuern, siehe Entra ID |
| Anmeldung hängt nach der Weiterleitung | Der Server erreicht den Anbieter nicht | Ausgehende Firewall prüfen, bis dahin lokales Konto nutzen |
| Direkt nach der Anmeldung wieder abgemeldet | APP_BASE_URL passt nicht zur Adresse im Browser oder TRUST_PROXY fehlt |
Beide Werte prüfen, siehe HTTPS |
| Lokales Konto gesperrt | Zu viele Fehlversuche | 15 Minuten warten, oder ein Admin setzt das Passwort zurück |
Admin-Passwort verloren:
docker compose exec contracthub node dist/reset-admin-password.js
Fehlgeschlagene Mails stehen mit der Meldung des Mailservers unter Verwaltung → Benachrichtigungen. Die häufigsten Ursachen findest du unter Mailversand.
Dokumente
Meldung „Datei fehlt“ beim Öffnen eines Dokuments:
docker compose exec contracthub node dist/storage.js check
ls -ln /opt/contracthub/files
Der Ordner files muss UID und GID 1000 gehören.
Speicherplatz
Ein voller Datenträger ist die häufigste Ursache für Störungen an den Containern selbst. Prüfe df -h und df -i. Images, Datenbank, Dokumente und Backups brauchen Platz, während eines Backups zusätzlich vorübergehend in der Größe des Datenbank-Dumps.
Informationen für den Support
Schick uns bei einer Anfrage bitte diese Ausgaben mit, aber keine Passwörter und keine .env-Dateien:
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
Die Logs enthalten keine Passwörter oder Schlüssel, Kontris schwärzt sie.
Stand 15.11.2026 · Kommst du nicht weiter? Schreib uns