Häufige Fehler
HTTP-Fehler
401 Unauthorized
| Symptom | API-Anfragen geben 401 zurück, oder die UI leitet Sie unerwartet zur Anmeldeseite weiter |
| Ursache | Ihre OAuth2-Sitzung ist abgelaufen oder das Token ist ungültig |
| Lösung | Melden Sie sich ab und melden Sie sich wieder an. Wenn das Problem nach der erneuten Anmeldung weiterhin besteht, löschen Sie Browser-Cookies und localStorage für die OpSee-Domain und melden Sie sich erneut an. Weitere Details finden Sie unter Anmeldungsprobleme. |
403 Forbidden
| Symptom | Die Seite wird geladen, aber die Daten werden nicht angezeigt, oder eine Aktion gibt einen 403-Fehler zurück |
| Ursache | Ihr Keycloak-Konto hat nicht die erforderliche Rolle für diese Ressource |
| Lösung | Wenden Sie sich an Ihren Keycloak-Administrator, um Ihre Rollenzuordnungen zu überprüfen. Überprüfen Sie Ihre aktuellen Rollen in Profil → Rollen und Berechtigungen. Häufig benötigte Rollen: menu:production, equipment:view, menu:admin. |
404 Not Found
| Symptom | Eine Seite oder ein API-Endpunkt gibt 404 zurück |
| Ursache | Die URL existiert nicht (Tippfehler, veraltetes Lesezeichen) oder das Modul ist in dieser Instanz nicht bereitgestellt |
| Lösung | Navigieren Sie von der Hauptmenü zur Seite. Wenn der Menüpunkt selbst fehlt, ist die Funktion möglicherweise nicht in Ihrer Bereitstellung aktiviert. Wenden Sie sich an Ihren Administrator. |
500 Internal Server Error
| Symptom | Eine Aktion schlägt mit einer generischen Serverfehlermeldung fehl |
| Ursache | Eine nicht behandelte Ausnahme in der Backend-API |
| Lösung | Überprüfen Sie die Backend-Container-Protokolle (docker logs opsee-fastapi). Wenn der Fehler reproduzierbar ist, notieren Sie die genaue Aktion, die ihn auslöst, und melden Sie ihn Ihrem Administrator mit dem Zeitstempel, damit dieser den Logeintrag korrelieren kann. |
502 Bad Gateway / 503 Service Unavailable
| Symptom | Die gesamte Anwendung zeigt eine 502- oder 503-Fehlerseite an |
| Ursache | Der Backend-Dienst oder eine seiner Abhängigkeiten (Datenbank, Keycloak) ist nicht verfügbar oder noch nicht gestartet |
| Lösung | Führen Sie docker ps auf dem Server aus, um zu überprüfen, welche Container ausgeführt werden. Starten Sie beendete Container mit docker compose up -d neu. Wenn die Datenbank das Problem ist, überprüfen Sie auf Speicherplatzerschöpfung oder Verbindungslimitfehler. |
Netzwerkfehler
„Keine Verbindung" / Netzwerkfehler
| Symptom | API-Aufrufe schlagen in der Browser-Konsole mit einem Netzwerkfehler fehl; es wird kein HTTP-Statuscode zurückgegeben |
| Ursache | Der OpSee-Backend-Container wird nicht ausgeführt, oder der NGINX-Reverse-Proxy kann ihn nicht erreichen |
| Lösung | Überprüfen Sie, dass Docker-Container ausgeführt werden: docker ps. Wenn der Backend-Container beendet ist, inspektieren Sie seine Protokolle mit docker logs opsee-fastapi. Starten Sie mit docker compose up -d neu. |
Formularvalidierungsfehler
Erforderliches Feld / ungültiges Format
| Symptom | Ein Formular lehnt die Übermittlung ab und markiert Felder rot |
| Ursache | Ein erforderliches Feld ist leer, ein Wert entspricht nicht dem erwarteten Format (z.B. ein Datumsfeld enthält Text) oder die Eingabe überschreitet die maximale Länge |
| Lösung | Füllen Sie alle markierten Felder. Achten Sie auf Formathints, die unter jedem Feld angezeigt werden. |
Doppelter Eintrag
| Symptom | Das Formular wird übermittelt, gibt aber einen Fehler wie „bereits vorhanden" oder „doppelter Schlüssel" zurück |
| Ursache | Ein Datensatz mit demselben eindeutigen Bezeichner (Name, Code usw.) existiert bereits in der Datenbank |
| Lösung | Verwenden Sie einen anderen Wert für das eindeutige Feld, oder bearbeiten Sie den vorhandenen Datensatz, anstatt einen neuen zu erstellen. |