Prima il quadro generale, dalla cartella dell’installazione:
./draften status # versione, stato di entrambi i colori web e dei worker, HTTPS, dump del database
Poi più nel dettaglio:
docker compose ps # i servizi sono attivi, il database è in salute?
docker compose logs --tail 50 worker # le ultime voci del worker
docker compose run --rm worker node diag.mjs mailbox@company.com
L’ultimo fa la stessa cosa di Testa la connessione nell’interfaccia: prende l’accesso salvato per la casella, ottiene un token, stampa le sue autorizzazioni (mai il token stesso) e legge la posta in arrivo.
Errori comuni
| Sintomo | Causa | Cosa fare |
|---|---|---|
set DB_PASSWORD in .env all’avvio | mancano le password del database | compila .env |
mailbox … has no access yet | la casella non ha una registrazione né un account collegato | pagina della casella → Accesso alla posta |
| “L’organizzazione non ha configurato un client Microsoft 365 o Google.” quando si collega una casella con l’account | l’organizzazione non ha un client nel riquadro Accesso con account e collegamento delle caselle | lo aggiunge un proprietario dell’organizzazione – vedi Microsoft 365 o Google Workspace, client dell’organizzazione |
Graph … 401 … invalid_client | client secret errato o scaduto | un nuovo segreto nella registrazione, poi il test della connessione |
Graph … 403 … AppOnly AccessPolicy | la policy di accesso dell’applicazione non è ancora in vigore, oppure la casella non è nel gruppo | aspetta (anche ore), ripeti il test; aggiungi la casella al gruppo |
Graph … 403 … ErrorAccessDenied | manca il consenso dell’amministratore | in Entra, Grant admin consent nella registrazione |
Category not added … MailboxSettings | manca l’autorizzazione MailboxSettings.ReadWrite; l’etichetta funziona, solo senza colore | aggiungi l’autorizzazione e il consenso |
No active assistant in the database | l’assistente è disattivato, oppure i dati iniziali non sono stati configurati | attiva l’assistente; controlla il log di avvio |
| l’assistente viene saltato (“no prompts yet”) | l’assistente non ha istruzioni scritte | completa la procedura guidata, oppure scrivi le istruzioni a mano |
| il campione nella procedura guidata segnala dati insufficienti | il proprietario rispondeva prima da un altro indirizzo (per esempio prima di un cambio di dominio) e la procedura guidata non conta quelle risposte come sue | aggiungi l’indirizzo nel campo Altri indirizzi della casella (accanto al campione, nel passaggio Periodo o nella pagina della casella) e scegli di nuovo il campione; l’indirizzo intero, non solo il dominio |
Draft without signature / links outside the allowed domains | la bozza non ha superato un controllo | guarda il messaggio – potrebbe essere un tentativo di falsificazione |
Limit reached | il limite giornaliero o per mittente | aumentalo solo se l’ondata di posta è legittima |
Model refused to answer | il filtro di sicurezza del modello | gestisci il messaggio a mano |
Model exhausted max_iterations | il modello è finito in un ciclo con i suoi strumenti | ritentato due volte; se si ripete, metti a punto l’istruzione Compito |
ECONNREFUSED … 3306 | il database non è attivo o non è ancora partito | docker compose ps, docker compose logs db |
| la barra “La licenza è scaduta” o “L’installazione non ha una licenza”, gli assistenti non scrivono nulla | la licenza manca o è scaduta | carica una licenza valida – vedi La licenza |
il servizio web per un attimo non risponde e le richieste in corso vanno perse; nel log del servizio web (docker compose logs web-blue web-green) c’è un riavvio | una richiesta ha superato il limite rigido di memoria di PHP (da PHP 8.5.12 il doppio di memory_limit) e PHP ha terminato l’intero processo web | Docker riavvia il servizio web da solo, di solito entro qualche decina di secondi; se si ripete, cerca nel log la richiesta che ha superato il limite |
| un aggiornamento è finito con un errore | la nuova versione non è diventata sana; quella precedente continua a servire | l’errore in Richieste o nell’output di ./draften update; ./draften status |
| il servizio web restituisce 502 dopo il riavvio del server | le versioni precedenti al 30 ottobre 2026 commutavano il servizio web in un modo per cui Docker considerava il proxy fermato a mano, e quindi non lo faceva ripartire al riavvio della macchina | nella directory dell’installazione, docker compose up -d --no-deps proxy; lo risolve definitivamente l’aggiornamento alla versione del 30 ottobre 2026 o successiva |
| “L’ultimo backup giornaliero non è riuscito” nel riquadro Backup del database | il dump del database non è riuscito (il messaggio è nel riquadro); si riprova un’ora dopo | esegui ./draften backup e leggi l’errore; controlla lo spazio libero su disco (df -h) e ./draften status |
Quando il log non lo mostra
- L’interfaccia: le Impostazioni dell’assistente → Attività (controlli della posta, richieste, eventi) e la pagina Gestione (worker, coda, errori delle ultime 24 ore).
- Dopo tre tentativi non riusciti un messaggio riceve lo stato non riuscito; l’ultimo errore è nel suo dettaglio.
Un passaggio singolo a mano
docker compose run --rm worker node worker.mjs --dry-run
Prende una volta ogni assistente attivo e forza la modalità di prova – nella posta non viene scritto nulla. Utile per verificare che tutto funzioni.
Quando ti serve il nostro aiuto
./draften diagnose
scrive un file diagnose-<ora>.tar.gz con lo stato dell’installazione, le versioni, la configurazione senza segreti e la parte finale dei log. Inviacelo.
Prima di inviare il file, guarda cosa contiene: i log possono contenere indirizzi e oggetti della posta elaborata. Nulla lascia il server da solo.