Errori Comuni
Errori HTTP
401 Unauthorized
| Sintomo | Le richieste API restituiscono 401, oppure l'interfaccia reindirizza inaspettatamente alla pagina di login |
| Causa | La sessione OAuth2 è scaduta o il token non è valido |
| Soluzione | Esci ed effettua nuovamente l'accesso. Se il problema persiste dopo il re-login, cancella i cookie del browser e il localStorage per il dominio OpSee, poi accedi di nuovo. Vedi Problemi di Login per maggiori dettagli. |
403 Forbidden
| Sintomo | La pagina si carica ma i dati non compaiono, oppure un'azione restituisce un errore 403 |
| Causa | Il tuo account Keycloak non ha il ruolo richiesto per questa risorsa |
| Soluzione | Contatta il tuo amministratore Keycloak per verificare le assegnazioni dei ruoli. Controlla i tuoi ruoli attuali in Profilo → Ruoli e Permessi. Ruoli comunemente necessari: menu:production, equipment:view, menu:admin. |
404 Not Found
| Sintomo | Una pagina o un endpoint API restituisce 404 |
| Causa | L'URL non esiste (errore di battitura, segnalibro obsoleto) oppure il modulo non è installato in questa istanza |
| Soluzione | Naviga alla pagina dal menu principale. Se la voce di menu stessa è assente, la funzionalità potrebbe non essere abilitata nel tuo deployment, contatta il tuo amministratore. |
500 Internal Server Error
| Sintomo | Un'azione fallisce con un messaggio di errore generico del server |
| Causa | Un'eccezione non gestita nel backend API |
| Soluzione | Controlla i log del container backend (docker logs opsee-fastapi). Se l'errore è riproducibile, annota l'azione esatta che lo provoca e segnalalo al tuo amministratore con il timestamp così che possa correlarlo alla voce di log. |
502 Bad Gateway / 503 Service Unavailable
| Sintomo | L'intera applicazione mostra una pagina di errore 502 o 503 |
| Causa | Il servizio backend o una delle sue dipendenze (database, Keycloak) è inattivo o non ancora avviato |
| Soluzione | Esegui docker ps sul server per verificare quali container sono in esecuzione. Riavvia i container fermi con docker compose up -d. Se il problema è il database, controlla l'esaurimento dello spazio su disco o errori di limite di connessione. |
Errori di Rete
"Cannot connect" / Errore di rete
| Sintomo | Le chiamate API falliscono con un errore di rete nella console del browser; non viene restituito alcun codice di stato HTTP |
| Causa | Il container backend di OpSee non è in esecuzione, oppure il reverse proxy NGINX non riesce a raggiungerlo |
| Soluzione | Verifica che i container Docker siano attivi: docker ps. Se il container backend è uscito, ispeziona i suoi log con docker logs opsee-fastapi. Riavvia con docker compose up -d. |
Errori di Validazione dei Form
Campo obbligatorio / formato non valido
| Sintomo | Un form rifiuta di essere inviato ed evidenzia i campi in rosso |
| Causa | Un campo obbligatorio è vuoto, un valore non corrisponde al formato previsto (ad esempio un campo data contiene del testo), oppure l'input supera la lunghezza massima |
| Soluzione | Compila tutti i campi evidenziati. Presta attenzione ai suggerimenti di formato visualizzati sotto ogni campo. |
Voce duplicata
| Sintomo | Il form viene inviato ma restituisce un errore tipo "esiste già" o "chiave duplicata" |
| Causa | Un record con lo stesso identificatore univoco (nome, codice, ecc.) esiste già nel database |
| Soluzione | Usa un valore diverso per il campo univoco, oppure modifica il record esistente invece di crearne uno nuovo. |