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

Mail

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