Risoluzione dei Problemi

Questa guida copre i problemi piu frequenti nell'utilizzo di Rela AI e come risolverli.

Problemi di Connessione WhatsApp

Il codice QR non appare

Causa: Il server WhatsApp non riesce a generare la sessione, generalmente a causa di un problema di rete o di una sessione gia attiva.

Soluzione:

Verifica che la tua connessione internet sia stabile.
Se avevi gia una sessione attiva, disconnettila prima dal pannello di controllo.
Ricarica la pagina e richiedi nuovamente il codice QR.
Se il problema persiste, attendi 2-3 minuti prima di riprovare. WhatsApp impone limiti di frequenza.

L'agente si disconnette frequentemente

Causa: WhatsApp chiude le sessioni inattive o quando rileva connessioni multiple dallo stesso numero.

Soluzione:

Assicurati di non avere WhatsApp Web aperto in un altro browser o dispositivo contemporaneamente.
Verifica che il tuo telefono abbia una connessione internet stabile.
Riconnetti l'agente dalla dashboard e scansiona nuovamente il QR.

I messaggi non arrivano all'agente

Causa: La sessione WhatsApp e disconnessa o il webhook non e configurato correttamente.

Soluzione:

Controlla lo stato della connessione dell'agente nella dashboard. Deve mostrare "Connesso".
Se appare disconnesso, riconnetti scansionando il codice QR.
Verifica che il numero di destinazione non sia bloccato.
Controlla i log dell'agente per confermare che i messaggi vengono ricevuti.

Problemi di Email

L'account email non si verifica

Causa: I record DNS (SPF, DKIM, MX) non sono configurati correttamente nel tuo dominio.

Soluzione:

Vai alla configurazione dell'agente email e copia i record DNS richiesti.
Accedi al pannello di amministrazione del tuo dominio (GoDaddy, Cloudflare, ecc.).
Aggiungi i record TXT per SPF e DKIM esattamente come mostrato.
Aggiungi il record MX che punta al server Rela AI.
Attendi fino a 48 ore per la propagazione DNS. Puoi verificare lo stato con strumenti come MXToolbox.

I record DNS sono configurati ma la verifica fallisce

Causa: Propagazione DNS incompleta o record con formato errato.

Soluzione:

Verifica che non ci siano spazi extra o caratteri invisibili nei record.
Conferma che il TTL non sia eccessivamente alto (consigliato: 3600 o inferiore).
Usa dig TXT tuodominio.com o MXToolbox per confermare che i record siano visibili.
Se usi Cloudflare, assicurati che il proxy sia disattivato per i record email.

Le email inviate dall'agente non arrivano al destinatario

Causa: Le email potrebbero essere contrassegnate come spam o i record DNS non sono completi.

Soluzione:

Chiedi al destinatario di controllare la cartella spam/posta indesiderata.
Verifica che SPF e DKIM siano configurati correttamente.
Controlla i log dell'agente per confermare che l'email sia stata inviata con successo.
Se il dominio e nuovo, potrebbe aver bisogno di tempo per costruire la reputazione. Invia prima email di prova.

Problemi di Eventi e Allarmi (Machine Agents)

Gli eventi non vengono elaborati

Causa: La connessione al broker MQTT o al server OPC UA e interrotta, oppure il formato dell'evento non e valido.

Soluzione:

Controlla lo stato della connessione del machine agent nella dashboard.
Conferma che le credenziali del broker MQTT (host, porta, utente, password) siano corrette.
Verifica che il topic MQTT a cui l'agente e iscritto sia corretto.
Controlla che il payload dell'evento sia un JSON valido.

La connessione MQTT fallisce

Causa: Porta bloccata dal firewall, credenziali errate o broker non disponibile.

Soluzione:

Verifica che la porta 1883 (o 8883 per TLS) sia aperta nel tuo firewall.
Testa la connessione manualmente con un client MQTT come MQTTX o mosquitto_sub.
Conferma che il broker sia in esecuzione e accetti connessioni esterne.
Se usi TLS, verifica che i certificati siano validi e non scaduti.

La connessione OPC UA fallisce

Causa: URL dell'endpoint errato, certificati non affidabili o politica di sicurezza incompatibile.

Soluzione:

Verifica che l'URL dell'endpoint OPC UA sia accessibile dal server Rela AI.
Conferma che la politica di sicurezza configurata corrisponda a quella del server OPC UA.
Se il server richiede certificati, assicurati che siano installati correttamente.
Controlla i log per messaggi di errore specifici del protocollo OPC UA.

Problemi degli Strumenti (Tools)

Lo strumento non viene eseguito

Causa: Lo schema dello strumento e mal configurato, l'endpoint non risponde o l'agente non ha lo strumento assegnato.

Soluzione:

Verifica che lo strumento sia assegnato all'agente nella sezione di configurazione.
Conferma che l'URL dell'endpoint sia accessibile e risponda correttamente.
Testa l'endpoint manualmente con uno strumento come Postman o curl.
Controlla che lo schema JSON dei parametri sia valido.

I parametri vengono inviati in modo errato

Causa: Lo schema dei parametri non corrisponde a cio che l'endpoint si aspetta, o la descrizione dello strumento e ambigua per il modello IA.

Soluzione:

Rivedi la definizione dello schema dello strumento. Ogni parametro deve avere tipo, descrizione e flag required.
Migliora le descrizioni dei parametri affinche il modello IA possa inferire correttamente i valori.
Usa il campo description dello strumento per spiegare chiaramente quando e come deve essere usato.
Controlla i log per vedere quali parametri l'agente sta inviando all'endpoint.

Problemi di Estrazione Dati

Il documento non viene elaborato

Causa: Formato file non supportato, file corrotto o dimensione eccessiva.

Soluzione:

Verifica che il file sia un PDF, un'immagine (PNG, JPG) o un formato supportato.
Conferma che la dimensione del file non superi il limite (generalmente 10 MB).
Se e un PDF scansionato, assicurati che la qualita dell'immagine sia leggibile.
Prova con una versione diversa del documento o convertilo in PDF.

I campi non vengono rilevati correttamente

Causa: La struttura del documento non corrisponde al template di estrazione o la qualita del documento e bassa.

Soluzione:

Rivedi la struttura di estrazione (report_structure) e conferma che i key_value corrispondano alle etichette del documento.
Se il documento ha un formato non standard, modifica le descrizioni dei campi nel template.
Migliora la qualita del documento: risoluzione maggiore, senza filigrane, testo leggibile.
Testa con documenti di esempio per validare il template prima di usarlo in produzione.

Problemi Generali

La sessione scade costantemente

Causa: Il token di autenticazione ha una durata limitata o ci sono problemi con i cookie del browser.

Soluzione:

Esci e accedi nuovamente.
Cancella i cookie e la cache del browser per il dominio Rela AI.
Verifica che l'orologio del tuo sistema sia sincronizzato correttamente.
Se usi una VPN, prova senza per escludere problemi di rete.

Errore di permessi ("Non autorizzato" o "Forbidden")

Causa: Il tuo ruolo nell'organizzazione non ha i permessi necessari per l'azione richiesta.

Soluzione:

Controlla il tuo ruolo attuale nella sezione Organizzazione della dashboard.
Contatta l'amministratore della tua organizzazione per richiedere i permessi necessari.
I ruoli disponibili sono: Admin, Manager e Viewer. Solo Admin e Manager possono modificare gli agenti.

Limiti dell'API (Rate Limiting)

Causa: E stato superato il numero massimo di richieste consentite in un periodo di tempo.

Soluzione:

Attendi qualche minuto prima di riprovare. I limiti si resettano automaticamente.
Se usi l'API direttamente, implementa la logica di retry con backoff esponenziale.
Controlla gli header di risposta X-RateLimit-Remaining e X-RateLimit-Reset per gestire le tue richieste.
Se hai bisogno di limiti piu alti, contatta il team di supporto.

Problemi di Manutenzione

Piano eseguito ma nessun task creato

Causa: Il piano di manutenzione non ha un dipartimento assegnato, quindi il sistema non puo determinare a chi assegnare il task.

Soluzione:

Vai al piano di manutenzione in questione.
Verifica che il campo department_id sia assegnato correttamente.
Salva il piano e attendi la prossima esecuzione programmata.

Notifica non inviata

Causa: La persona assegnata non ha un'email o un numero di telefono configurato nel proprio profilo.

Soluzione:

Vai al profilo dell'utente nella sezione Organizzazione.
Verifica che abbia un'email o un numero di telefono registrato.
Salva le modifiche e riprova l'azione che genera la notifica.

Il piano non si esegue automaticamente

Causa: Il piano e disabilitato o in pausa.

Soluzione:

Apri il piano di manutenzione.
Verifica che il toggle Abilitato sia attivo.
Conferma che il piano non sia nello stato In pausa.
Controlla che la programmazione (cron o data) sia corretta e non sia passata.

Il contatore non si attiva

Causa: Il valore di counter_threshold e 0 o non e configurato.

Soluzione:

Apri il piano di manutenzione basato su contatore.
Verifica che counter_threshold sia maggiore di 0.
Conferma che il contatore dell'asset si stia incrementando correttamente.

Problemi LOTO (Lockout/Tagout)

"Nessuna procedura approvata"

Causa: Si sta tentando di avviare un'esecuzione LOTO ma non esiste una procedura approvata per l'asset.

Soluzione:

Vai alla sezione LOTO e crea una procedura per l'asset.
Completa tutti i passaggi richiesti della procedura.
Invia la procedura per l'approvazione e attendi che venga approvata.
Una volta approvata, potrai avviare l'esecuzione LOTO.

L'asset rimane bloccato

Causa: L'esecuzione LOTO non e stata completata correttamente.

Soluzione:

Vai a /loto/executions/{id} dove {id} e l'ID dell'esecuzione attiva.
Clicca su Sblocca per rilasciare l'asset.
Verifica che tutti i passaggi di sblocco siano stati completati.

Non posso interrompere l'esecuzione

Causa: La richiesta di interruzione richiede un body con il motivo della cancellazione.

Soluzione:

Quando effettui la richiesta di interruzione, includi un body con il campo reason.
Esempio: {"reason": "Emergenza risolta, non piu necessario"}.
Il motivo e obbligatorio per ragioni di audit.

Problemi di Ispezioni

I checkpoint non vengono salvati

Causa: I checkpoint vanno persi se il progresso non viene salvato prima di completare o uscire dalla pagina.

Soluzione:

Clicca su Salva periodicamente mentre completi i checkpoint.
Non chiudere la pagina senza aver salvato prima.
Se hai perso dei dati, dovrai ricompletare i checkpoint interessati.

Non posso completare l'ispezione

Causa: Tutti i checkpoint devono avere un segno di pass o fail prima di poter completare l'ispezione.

Soluzione:

Rivedi tutti i checkpoint dell'ispezione.
Segna ciascuno come Pass o Fail.
Una volta che tutti sono segnati, il pulsante Completa sara abilitato.

Template senza checkpoint

Causa: Il template di ispezione e stato creato senza aggiungere checkpoint.

Soluzione:

Modifica il template di ispezione.
Aggiungi i checkpoint necessari nella sezione corrispondente.
Salva il template prima di usarlo per creare ispezioni.

Problemi di Anomalie ML

"Insufficient data" durante l'addestramento

Causa: Il modello di rilevamento anomalie necessita di una quantita minima di dati storici per l'addestramento.

Soluzione:

Assicurati che l'asset abbia almeno 10 letture storiche registrate (idealmente 100 o piu).
Attendi che si accumulino dati sufficienti prima di tentare l'addestramento.
Verifica che le letture stiano arrivando correttamente al sistema.

Il modello non rileva nulla

Causa: La sensibilita del modello e configurata troppo bassa per i dati attuali.

Soluzione:

Vai alla configurazione del modello di anomalie.
Cambia la sensibilita a high per rilevare deviazioni piu piccole.
Ri-addestra il modello se necessario.
Verifica che i dati in ingresso abbiano sufficiente variabilita.

Troppi falsi positivi

Causa: La sensibilita del modello e troppo alta, rilevando variazioni normali come anomalie.

Soluzione:

Riduci la sensibilita a low nella configurazione del modello.
Ri-addestra il modello con un set di dati piu rappresentativo.
Rivedi e ignora le anomalie false per migliorare l'apprendimento del modello.

Problemi SPC (Controllo Statistico di Processo)

"Invalid chart_type"

Causa: Il tipo di carta SPC deve usare il formato con underscore, non trattini o spazi.

Soluzione:

Usa i valori validi: x_bar_r, x_bar_s, i_mr.
Non usare formati come x-bar-r, xBarR o X Bar R.
Verifica il valore esatto nella documentazione dell'API.

Nessun limite di controllo

Causa: Il sistema necessita di una quantita minima di dati per calcolare i limiti di controllo (UCL, LCL).

Soluzione:

Registra almeno 10 sottogruppi di dati prima di aspettarti limiti calcolati.
Idealmente, usa 25 o piu sottogruppi per limiti piu stabili.
I limiti vengono calcolati automaticamente una volta che ci sono dati sufficienti.

Capability (Cp/Cpk) mostra "—"

Causa: I limiti di specifica (USL e LSL) non sono definiti nella carta SPC.

Soluzione:

Modifica la carta SPC.
Definisci l'USL (Upper Specification Limit) e l'LSL (Lower Specification Limit).
Salva le modifiche. Gli indici Cp e Cpk verranno calcolati automaticamente.

Hai bisogno di ulteriore aiuto?

Se il tuo problema non e coperto in questa guida:

Controlla i log dell'agente nella dashboard per i dettagli dell'errore.
Contatta il team di supporto tramite la chat nella piattaforma.
Invia un'email a soporte@rela-ai.com con una descrizione del problema, screenshot e log pertinenti.

Risoluzione dei Problemi

In questa pagina