Risoluzione dei problemi
Questa pagina tratta i problemi più comuni riscontrati nelle installazioni self-hosted di Gäld e come risolverli. Per la versione cloud (EE), contatta il supporto se il problema persiste dopo aver seguito questi passaggi.
Il worker della coda non elabora i job
Sintomi: Fatture ricorrenti non generate, email di sollecito non inviate, esportazione fiduciaria bloccata.
Causa: Il worker della coda (Laravel Horizon o il processo queue:work) non è in esecuzione.
Soluzione:
# Controlla lo stato
sudo systemctl status gaeld-worker
# Riavvia il worker
sudo systemctl restart gaeld-worker
# Visualizza i job falliti recenti
php artisan queue:failed
Se vedi dei job falliti, riprovali:
php artisan queue:retry all
Per svuotare la lista dei job falliti dopo aver risolto il problema sottostante:
php artisan queue:flush
Vedi Self-Hosting per la configurazione completa del servizio systemd.
MeiliSearch non disponibile / la ricerca non restituisce risultati
Sintomi: Contatti, fatture o spese non trovabili tramite la barra di ricerca; messaggio di errore «Ricerca non disponibile».
Causa: MeiliSearch non è in esecuzione o l'indice non è stato popolato.
Soluzione:
# Controlla lo stato di MeiliSearch
sudo systemctl status meilisearch
# Riavvia MeiliSearch
sudo systemctl restart meilisearch
# Reindicizza tutti i dati (esegui dalla directory dell'applicazione)
php artisan scout:import "App\Domains\Invoicing\Models\Invoice"
php artisan scout:import "App\Domains\Contacts\Models\Contact"
php artisan scout:import "App\Domains\Expenses\Models\Expense"
Se MeiliSearch non è disponibile, Gäld passa automaticamente alla ricerca nel database. I risultati possono essere più lenti e meno fuzzy, ma l'applicazione continua a funzionare.
L'importazione CAMT.053 fallisce o non produce transazioni
Sintomi: Il caricamento di un estratto conto produce un errore o importa 0 transazioni.
Cause comuni e soluzioni:
| Causa | Soluzione |
|---|---|
| Il file non è un XML CAMT.053 valido | Controlla l'estensione del file e conferma che la banca esporta CAMT.053, non CAMT.054 o MT940 |
| Il file contiene transazioni per un IBAN diverso | Aggiungi quell'IBAN come conto bancario in Impostazioni → Conti bancari, poi reimporta |
| Il file è già stato importato | Gäld rileva i duplicati tramite hash del file — scarica una nuova esportazione dalla banca per un intervallo di date diverso |
| L'XML è malformato | Apri il file in un editor di testo e verifica che inizi con <?xml e contenga <Document> |
Se l'errore persiste, salva il file e contatta il supporto — includi il messaggio di errore mostrato da Gäld.
Il PDF della fattura non viene generato / il download è vuoto
Sintomi: Cliccando su Scarica PDF su una fattura finalizzata si ottiene una pagina vuota o un errore.
Causa: Solitamente un problema di configurazione TCPDF o un font mancante.
Soluzione:
- Controlla il log dell'applicazione per errori PDF:
tail -n 50 storage/logs/laravel.log | grep -i pdf
- Assicurati che la directory
storage/sia scrivibile:
chmod -R 775 storage/
chown -R www-data:www-data storage/
- Esegui i comandi artisan post-installazione:
php artisan storage:link
php artisan config:clear
php artisan cache:clear
Le email non vengono inviate (inviti, solleciti, buste paga)
Sintomi: Gli utenti invitati non ricevono le email di invito; i solleciti di pagamento non vengono recapitati.
Causa: La configurazione email è errata o il worker della coda non è in esecuzione.
Soluzione:
- Controlla Impostazioni → Email per la configurazione SMTP (host, porta, nome utente, password, crittografia)
- Clicca su Invia email di test per verificare la connessione
- Controlla che il worker della coda sia in esecuzione (vedi sopra)
- Controlla
storage/logs/laravel.logper errori SMTP:
grep -i "swift\|smtp\|mail" storage/logs/laravel.log | tail -20
Impostazioni SMTP comuni per provider svizzeri:
| Provider | Host | Porta | Crittografia |
|---|---|---|---|
| Infomaniak | mail.infomaniak.com | 587 | STARTTLS |
| Hostpoint | mail.hostpoint.ch | 587 | STARTTLS |
| GMX | mail.gmx.net | 587 | STARTTLS |
| Mailgun | smtp.mailgun.org | 587 | STARTTLS |
«Queste credenziali non corrispondono ai nostri registri» al login
Sintomi: Impossibile accedere nonostante si inseriscano email e password corretti.
Possibili cause:
- La password è stata cambiata da un altro admin
- Il 2FA è attivato e non stai inserendo il codice TOTP
- L'account si trova su un sottodominio di un'altra organizzazione
Soluzione:
- Usa Password dimenticata nella schermata di login
- Se il problema è il 2FA e hai perso il dispositivo, usa un codice di recupero (fornito quando il 2FA è stato configurato)
- Se non hai codici di recupero, il Proprietario dell'organizzazione deve disabilitare il 2FA per il tuo account sotto Impostazioni → Utenti → [tuo nome] → Disabilita 2FA
La chiusura annuale è disattivata / non disponibile
Sintomi: Il pulsante Chiusura annuale in Contabilità non è cliccabile.
Causa: Uno o più controlli prerequisiti non sono stati superati. Gäld richiede:
- Nessuna transazione bancaria non riconciliata per l'esercizio fiscale
- Nessuna fattura in stato Bozza con data nell'esercizio fiscale
- L'utente corrente ha il ruolo Proprietario o Admin
Soluzione:
- Vai su Banking → Riconciliazione e completa tutte le riconciliazioni in sospeso
- Vai su Fatture e finalizza o annulla le bozze datate nell'anno di chiusura
- Verifica il tuo ruolo in Impostazioni → Utenti
Comandi artisan (riferimento rapido self-hosted)
# Cancella tutte le cache
php artisan optimize:clear
# Riesegui le migrazioni (sicuro da eseguire ripetutamente)
php artisan migrate
# Controlla lo stato dell'applicazione
php artisan about
# Reindicizza la ricerca
php artisan scout:import "App\Domains\Invoicing\Models\Invoice"
php artisan scout:import "App\Domains\Contacts\Models\Contact"
php artisan scout:import "App\Domains\Expenses\Models\Expense"