FAQ Problemi comuni

Soluzioni ai problemi più frequenti durante l’uso di XIQUIL.

Vedo un errore di caricamento oppure il pulsante Riprova

Un errore di caricamento non significa che non esistono dati: XIQUIL lo mostra separatamente dall’elenco vuoto e, dove disponibile, offre Riprova. Premi Riprova prima di continuare; finché non sono stati caricati i dati del documento, le azioni che li modificano restano bloccate per evitare di salvare righe o totali incompleti.

Lo stesso criterio vale per i selettori e per le pagine che caricano dati aggiuntivi. Se non puoi verificare sessione o permessi, usa Riprova: solo una risposta di accesso non autorizzato (401) viene trattata come sessione assente.

Un’azione mostra un avviso di errore

Gli errori di salvataggio o di altre azioni possono comparire in linea, per esempio nella gestione degli allegati, oppure in un avviso persistente nella pagina. L’avviso resta visibile finché non lo chiudi. Un errore durante il caricamento, la modifica della descrizione o l’eliminazione di un allegato non conferma l’azione: controlla il messaggio e riprova se necessario.

Quando il server non fornisce un dettaglio utile, XIQUIL mostra un messaggio in italiano riferito all’operazione in corso. I messaggi di validazione e di accesso restano distinti.

Il browser mostra un avviso di certificato

Questo è normale per un’installazione locale. XIQUIL genera un certificato auto-firmato per HTTPS. Il browser non lo riconosce come attendibile perché non è stato emesso da un’autorità certificata.

Soluzione: clicca “Avanzate” e poi “Procedi” (o equivalente nel tuo browser). Questo non è un rischio di sicurezza nella tua rete locale.

Per eliminare l’avviso, puoi:

• Usare un reverse proxy con Let’s Encrypt
• Importare il certificato auto-generato nel tuo browser/sistema

Non riesco ad accedere a XIQUIL (connessione rifiutata)

Verifica che i container siano in esecuzione:

docker compose ps

Se il container xiquil_app non è in stato “Up”:

docker compose logs app

Cause comuni:

• Il container sta ancora avviandosi (primo avvio richiede 1-2 minuti)
• Errore nel DATABASE_URL (password non corrisponde)
• Porta già occupata da un altro programma

La pagina carica ma resta bianca

Questo può succedere se il frontend non si è compilato correttamente. Prova:

1. Svuota la cache del browser (Ctrl+Shift+R)
2. Riavvia il container: docker compose restart app
3. Controlla i log: docker compose logs app

Non riesco a pagare una scadenza

Per pagare una scadenza servono:

• Un fondo (conto corrente, carta, ecc.) con saldo sufficiente
• L’uscita/entrata deve essere nello stato “Non pagato”

Se il pulsante “Paga” non appare, verifica di avere i permessi di scrittura sull’ambito.

L’importazione XML non funziona

L’importazione supporta il formato FatturaPA XML standard. Verifica che:

• Il file sia un XML valido
• Il formato sia FatturaPA (non un formato proprietario)
• Il file non sia corrotto o troncato

Nei log (docker compose logs app) trovi dettagli sull’errore di parsing.

Perché una fattura elettronica richiede almeno una riga?

Il formato FatturaPA non ammette fatture senza righe di dettaglio. Per una fattura semplice aggiungi una sola riga; se ci sono più aliquote, inserisci almeno una riga per aliquota. XIQUIL ricava automaticamente il riepilogo IVA dalle righe, separando aliquota e natura.

Documento Generico e Registrazione Libera non cambiano: per scontrini, ricevute, bollette o registrazioni sintetiche puoi ancora usare la modalità senza voci.

Ho una foto o un PDF con i totali ma senza righe: cosa faccio?

XIQUIL riconosce i totali, ma non inventa il dettaglio di una fattura elettronica. Se il documento è una fattura, inserisci almeno la prima riga a mano. Se è in realtà uno scontrino, una ricevuta o una bolletta, classificalo come Documento Generico o Registrazione Libera, dove l’importo unico resta disponibile.

Una vecchia fattura senza righe si apre in sola lettura

È previsto per le fatture storiche salvate con la vecchia modalità. Il documento non viene convertito automaticamente: aggiungi manualmente la prima riga e tornerà modificabile.

Il database occupa troppo spazio

# Verifica la dimensione del volume DB
docker compose exec db sh -c "du -sh /var/lib/postgresql/"

Per liberare spazio:

• Elimina i backup vecchi dalla sezione Impostazioni
• Esegui un VACUUM sul database:

docker compose exec db psql -U xiquil -d xiquil -c "VACUUM FULL"

I log mostrano errori di migrazione

Se il container non parte con errori di migrazione Alembic:

1. Controlla l’errore specifico nei log
2. Se è “Target database is not up to date”, prova:

docker compose exec app alembic -c /app/backend/alembic.ini stamp head
docker compose restart app

3. Se il problema persiste, fai un backup e contatta il supporto

Come leggo i log dell’applicazione?

# Log in tempo reale
docker compose logs -f app

# Ultimi 100 righe
docker compose logs --tail 100 app

# Log degli ultimi 10 minuti
docker compose logs --since 10m app

Dalla UI: se hai i permessi, la pagina Log mostra i log in tempo reale via streaming.

Mi sono registrato all’Hub ma non ho ricevuto l’email di verifica

1. Controlla la cartella spam o posta indesiderata. Il dominio xiquil.com è recente (aprile 2026) e provider come Gmail/Outlook tendono a filtrarlo finché non hanno costruito reputation. Se trovi l’email nello spam, contrassegnala come “non spam” e aggiungi [email protected] ai tuoi contatti.
2. Verifica di aver inserito l’indirizzo email corretto al momento della registrazione.
3. Aspetta qualche minuto (max 5 — l’invio è asincrono ma quasi sempre immediato).
4. Dalla pagina di verifica email clicca “Non hai ricevuto il codice? Invia di nuovo”. Il limite è 3 reinvii per ora; tra un click e il successivo ci sono 60 secondi di attesa.
5. Se persiste, l’amministratore dell’Hub può verificare lo stato SMTP nei log del backoffice.

Il codice di verifica è scaduto

Il codice a 6 cifre dura 15 minuti. Se hai aspettato troppo:

1. Torna sulla pagina Verifica email (sei loggato anche se non hai verificato — vai su https://hub.xiquil.com/verify-email)
2. Clicca “Invia di nuovo” per ricevere un nuovo codice
3. Inseriscilo entro 15 minuti dall’invio

Codici precedenti vengono invalidati appena ne richiedi uno nuovo.

Mi sono registrato ma non ho ricevuto l’activation key Starter

L’activation key arriva con la seconda email (oggetto “Benvenuto su XIQUIL — la tua activation key Starter è pronta”) subito dopo la verifica del codice.

1. Controlla la cartella spam — vale lo stesso discorso del codice di verifica.
2. La key resta sempre disponibile nella tua dashboard hub.xiquil.com. Anche se l’email non arriva, accedi all’Hub e vai alla home: la activation key è mostrata con un bottone “copia”. Non c’è bisogno di attendere l’email.
3. Se la dashboard non mostra alcuna licenza, verifica nella sezione “Email” del backoffice (solo per admin) o contatta il supporto.

Il widget anti-bot non diventa verde / il pulsante “Crea account” resta disabilitato

Il widget di registrazione è Cloudflare Turnstile, normalmente invisibile e automatico:

1. Aspetta 5-10 secondi dopo aver caricato la pagina (a volte serve un controllo passivo del browser).
2. Se vedi una challenge visibile (checkbox o immagini), completala.
3. Disabilita estensioni che bloccano script di terze parti (uBlock, Privacy Badger, NoScript) sul dominio hub.xiquil.com.
4. Verifica di non essere in modalità navigazione privata estrema (Tor Browser, Brave Shields aggressivi).
5. Ricarica la pagina (Ctrl+Shift+R) — ogni token Turnstile ha vita limitata e si rigenera al refresh.

Se il problema persiste su un dominio diverso da hub.xiquil.com, l’amministratore deve verificare che la VITE_TURNSTILE_SITE_KEY configurata corrisponda al dominio sul pannello Cloudflare.

”Verifica anti-bot fallita” durante la registrazione

Significa che il token del widget è scaduto o è stato rifiutato dal server:

1. Ricarica la pagina (Ctrl+Shift+R) e ricompila il form da capo.
2. Non lasciare il form aperto per oltre 5 minuti senza submit — il token Turnstile scade.
3. Se ricarichi e l’errore si ripresenta, cancella i cookie del dominio e riprova.

Se sei un amministratore self-hosted che riceve sempre questo errore, verifica che TURNSTILE_SECRET_KEY (lato server) e VITE_TURNSTILE_SITE_KEY (lato build frontend) siano della stessa coppia di chiavi Cloudflare e che il dominio configurato includa quello da cui stai accedendo.

Come posso chiedere aiuto?

1. GitHub Issues: per bug e richieste di funzionalità — github.com/JustVitLab/xiquil/issues
2. Wiki: per guide e FAQ — questa wiki
3. Log: allega sempre i log quando segnali un problema

Processi pianificati — domande frequenti

Posso disattivare un processo pianificato? Sì. Tutti i job sono disattivabili da Impostazioni avanzate → Processi pianificati. Prima di disattivare, leggi la descrizione del job per capire gli effetti: alcuni job (come il backup) hanno impatto diretto sulla sicurezza dei dati. Vedi Processi pianificati per i dettagli su ogni job.

Cosa succede se un job fallisce? Il job viene marcato come “Errore” e riproverà all’orario successivo. L’ultimo errore è visibile nella UI accanto al job. Se un job fallisce ripetutamente, un messaggio di avviso appare nella dashboard admin e viene generata una notifica agli amministratori.

Dove vedo la cronologia delle esecuzioni? Da Impostazioni avanzate → Processi pianificati puoi vedere per ogni job: l’ultima esecuzione, lo stato dell’ultima esecuzione e il messaggio di errore (se presente). Una cronologia completa delle esecuzioni non è disponibile nell’interfaccia — per il log dettagliato usa la pagina Log di sistema.

Vedi anche

• Log di sistema — per diagnosticare errori
• FAQ Installazione — problemi durante l’installazione
• FAQ Sicurezza — problemi di autenticazione e sessioni