> For the complete documentation index, see [llms.txt](https://manuale.opencontent.it/manuali/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manuale.opencontent.it/manuali/manuale-operativo-interno/tenant-manager/troubleshooting.md).

# Troubleshooting

Questa sezione raccoglie i problemi più comuni che il team delivery può incontrare durante l'utilizzo del Tenant Manager, con le relative cause e procedure di risoluzione.

***

#### Tenant bloccato in uno stato transitorio

**Sintomo:** il tenant è rimasto in stato *Provisioning*, *Deploying*, *Archiving* o *Deleting* per più di qualche minuto e non avanza.

**Causa:** il workflow Windmill è andato in errore prima di inviare la callback al Tenant Manager. Il sistema non sa che il workflow è terminato e mantiene il blocco.

**Procedura:**

1. Apri la scheda del tenant
2. Se disponibile, clicca sul link al job Windmill per leggere il log e capire la causa dell'errore

<figure><img src="/files/zOxlYMFCo1JC9ov5CGyX" alt=""><figcaption></figcaption></figure>

3. Risolvi la causa (es. credenziali mancanti, risorsa già esistente, errore di rete)
4. Usa il pulsante **"Sblocca"** nella scheda del tenant per riportarlo allo stato precedente la transizione
5. Ritenta la transizione

<figure><img src="/files/DjmLcveUM8ss2VyNwXZF" alt=""><figcaption></figcaption></figure>

Se il problema persiste o il log Windmill non è disponibile, contatta il team sviluppo fornendo:

* UID del tenant
* Tipo di applicativo
* Timestamp dell'operazione
* Eventuale messaggio di errore visibile

***

#### Errore di validazione al salvataggio della configurazione

**Sintomo:** il salvataggio del form di configurazione restituisce un errore; i dati non vengono salvati.

**Causa:** uno o più campi non rispettano i vincoli definiti nello schema Form.io dell'applicativo (es. formato URL non valido, campo obbligatorio vuoto, valore fuori range).

**Procedura:**

1. Leggi il messaggio di errore visualizzato nel form — indica quale campo non è valido e perché
2. Correggi il valore e riprova

> `TODO: [SCREENSHOT: Esempio di errore di validazione inline nel form di configurazione]`

Se il messaggio di errore non è chiaro o il campo sembra corretto ma continua a fallire, contatta il team sviluppo specificando il tipo di applicativo e il campo incriminato.

***

#### La transizione di stato non avvia nessun workflow

**Sintomo:** cliccando "Attiva" o "Metti in produzione" il tenant cambia stato senza passare per lo stato transitorio e senza che apparentemente accada nulla in Windmill.

**Causa probabile:** per quel tipo di applicativo e quella transizione non è configurato nessun workflow Windmill. Il Tenant Manager avanza lo stato direttamente.

**Cosa fare:** verifica con il team sviluppo se il workflow è previsto per quell'applicativo e se è già stato configurato nel backoffice. In alcuni casi il comportamento è intenzionale (applicativi semplici che non richiedono provisioning automatico).

***

#### L'applicativo non funziona dopo l'attivazione

**Sintomo:** il tenant è in stato *Attivato* o *In produzione* ma l'applicativo non risponde, non si connette al sistema esterno o genera errori.

**Causa più comune:** credenziali o endpoint errati nella configurazione.

**Procedura:**

1. Apri la sezione **Configurazione** del tenant
2. Verifica endpoint, credenziali e tutti i campi obbligatori
3. Controlla che le credenziali siano quelle dell'ambiente corretto (non usare credenziali di produzione su QA o viceversa)
4. Salva le correzioni
5. Se l'applicativo non si aggiorna automaticamente, verifica se è necessario un redeployment (contatta il team sviluppo)

> `TODO: [SCREENSHOT: Sezione Configurazione — campi endpoint e credenziali]`

***

#### Impossibile accedere al Tenant Manager

**Sintomo:** la pagina di login non si carica o le credenziali vengono rifiutate.

**Procedura:**

1. Verifica di star usando l'URL corretto (QA vs Produzione)
2. Se usi login con SSO (Authentik), verifica che il tuo account sia attivo e che tu abbia i permessi necessari
3. Se il problema persiste, contatta il team ops

***

#### Il tenant è in produzione ma il servizio non è visibile ai cittadini

**Sintomo:** il tenant risulta *In produzione* nel Tenant Manager, ma il servizio non è accessibile dall'esterno.

**Cause possibili:**

| Causa                                           | Verifica                                                           | Soluzione                            |
| ----------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------ |
| Dominio non ancora configurato                  | Controlla se l'URL definitivo è impostato nella configurazione     | Imposta il dominio e aggiorna il DNS |
| Workflow di deploy non completato correttamente | Controlla il log del job Windmill associato all'ultima transizione | Contatta il team sviluppo            |
| Problema infrastrutturale (cluster, rete)       | Fuori dal perimetro del Tenant Manager                             | Contatta il team ops                 |

***

#### Non trovo il cliente nell'anagrafica durante la creazione del tenant

**Sintomo:** cercando il cliente nel form di creazione del tenant, il nome non appare nella lista.

**Causa:** il cliente non è ancora stato censito nel Tenant Manager.

**Procedura:**

1. Vai alla sezione **Clienti** del Tenant Manager
2. Crea una nuova voce con il nome dell'ente, il codice e lo slug

<figure><img src="/files/Kre5uLM5KZiPzujAmblZ" alt=""><figcaption></figcaption></figure>

> Se non hai i permessi per creare clienti, contatta chi gestisce l'anagrafica nel tuo team.