# Risoluzione dei problemi

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](/it/admin/licence) |
| 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` |
| “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.