Common Errors
HTTP Errors
401 Unauthorized
| Symptom | API requests return 401, or the UI redirects to the login page unexpectedly |
| Cause | Your OAuth2 session has expired or the token is invalid |
| Fix | Log out and log back in. If the problem persists after re-login, clear browser cookies and localStorage for the OpSee domain, then log in again. See Login Issues for more detail. |
403 Forbidden
| Symptom | The page loads but data does not appear, or an action returns a 403 error |
| Cause | Your account is missing the permission the endpoint requires, or the record belongs to equipment outside your equipment scope |
| Fix | Check Profile → Roles and Permissions. If the page is missing entirely, you lack its permission — ask your administrator for a business role (role:Operator, role:Supervisor, …) that grants it. If the page loads but data is empty, or the error mentions equipment, ask for the relevant equipment:* scope. Sign out and back in after any change. |
404 Not Found
| Symptom | A page or API endpoint returns 404 |
| Cause | The URL does not exist (typo, outdated bookmark) or the module is not deployed in this instance |
| Fix | Navigate to the page from the main menu. If the menu item itself is missing, the feature may not be enabled in your deployment. Contact your administrator. |
500 Internal Server Error
| Symptom | An action fails with a generic server error message |
| Cause | An unhandled exception in the backend API |
| Fix | Check the backend container logs (docker logs opsee-fastapi). If the error is reproducible, note the exact action that triggers it and report it to your administrator with the timestamp so they can correlate the log entry. |
502 Bad Gateway / 503 Service Unavailable
| Symptom | The entire application shows a 502 or 503 error page |
| Cause | The backend service or one of its dependencies (database, Keycloak) is down or not yet started |
| Fix | Run docker ps on the server to check which containers are running. Restart stopped containers with docker compose up -d. If the database is the issue, check for disk space exhaustion or connection limit errors. |
Network errors
"Cannot connect" / Network Error
| Symptom | API calls fail with a network error in the browser console; no HTTP status code is returned |
| Cause | The OpSee backend container is not running, or the NGINX reverse proxy cannot reach it |
| Fix | Verify Docker containers are up: docker ps. If the backend container has exited, inspect its logs with docker logs opsee-fastapi. Restart with docker compose up -d. |
Form validation errors
Required field / invalid format
| Symptom | A form refuses to submit and highlights fields in red |
| Cause | A required field is empty, a value does not match the expected format (e.g. a date field contains text), or the input exceeds the maximum length |
| Fix | Fill in all highlighted fields. Pay attention to format hints displayed below each field. |
Duplicate entry
| Symptom | The form submits but returns an error like "already exists" or "duplicate key" |
| Cause | A record with the same unique identifier (name, code, etc.) already exists in the database |
| Fix | Use a different value for the unique field, or edit the existing record instead of creating a new one. |