Risoluzione dei problemi — Guida di draften

Sintomo, causa e cosa fare – dall’accesso alla casella mancante a un segreto scaduto.

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
`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
`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
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`

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.