Troubleshooting - Risoluzione Problemi

Questa guida ti aiuta a risolvere i problemi più comuni. Se non trovi la soluzione, contatta il supporto.

🔴 Errori di Autenticazione

”Invalid email or password”

Causa: Credenziali errate o account non esistente.

Soluzioni:

1. Verifica che l’email sia scritta correttamente
2. Controlla il Caps Lock (le password sono case-sensitive)
3. Usa Password dimenticata per resettare
4. Se sei nuovo, devi prima registrarti

”Session expired”

Causa: Il token di sessione è scaduto dopo 1 ora di inattività.

Soluzione: Effettua nuovamente il login. I token vengono automaticamente rinnovati se usi l’app attivamente.

”Too many login attempts” (429)

Causa: Rate limiting attivato dopo 10 tentativi falliti.

Soluzione:

• Attendi 15 minuti prima di riprovare
• Assicurati di usare le credenziali corrette
• Considera di resettare la password

🌐 Problemi di Monitoraggio

Sito mostrato come “DOWN” ma è online

Cause possibili:

1. Firewall blocca il nostro IP: Aggiungi 149.102.XXX.XXX alla whitelist
2. Timeout: Il sito risponde lentamente (> 30s)
3. Geolocalizzazione: Il sito blocca richieste dall’Europa

Soluzioni:

# Testa manualmente
curl -I -m 10 https://tuo-sito.com

# Verifica che non blocchi robots
curl -A "PolipoBot/1.0" https://tuo-sito.com

Check SSL fallisce con “UNABLE_TO_VERIFY_LEAF_SIGNATURE”

Causa: Certificati intermedi mancanti nella chain SSL.

Soluzione:

1. Vai su SSL Labs e testa il tuo sito
2. Identifica i certificati intermedi mancanti
3. Configura il server per includerli:

# Nginx
ssl_certificate /path/to/fullchain.pem;  # Include intermediates
ssl_certificate_key /path/to/privkey.pem;

Check DNS mostra “NXDOMAIN”

Causa: Il dominio non ha record DNS configurati o è scaduto.

Verifica:

dig +short tuo-dominio.com
nslookup tuo-dominio.com

Soluzioni:

1. Verifica che il dominio sia attivo (non scaduto)
2. Configura i record DNS nel pannello del registrar
3. Attendi propagazione DNS (fino a 48 ore)

🖥️ Problemi Terminali

”Connection refused” su SSH

Cause:

1. Server SSH non in ascolto sulla porta
2. Firewall blocca la connessione
3. IP del server errato

Diagnosi:

# Testa connettività
telnet server-ip 22
nc -zv server-ip 22

# Verifica SSH status (sul server)
sudo systemctl status sshd

“Permission denied (publickey)”

Causa: Chiave SSH non configurata correttamente.

Soluzioni:

1. Verifica che la chiave pubblica sia in ~/.ssh/authorized_keys sul server
2. Controlla i permessi:

   chmod 700 ~/.ssh
   chmod 600 ~/.ssh/authorized_keys

3. Usa l’autenticazione con password temporaneamente

Terminale mostra “echo $TERM”

Causa: Il terminale non riceve input correttamente.

Soluzione: Ricarica la pagina (Ctrl+Shift+R) e riconnettiti.

🐳 Problemi Docker

”Cannot connect to Docker daemon”

Causa: Docker non è in esecuzione o l’utente non ha permessi.

Soluzioni:

# Verifica status Docker
sudo systemctl status docker
sudo systemctl start docker

# Aggiungi utente al gruppo docker
sudo usermod -aG docker $USER
# Riloggati per applicare

Container non si avvia

Diagnosi:

# Vedi log del container
docker logs container-name

# Verifica risorse
docker stats

Cause comuni:

• Porta già in uso: Cambia la porta esterna in docker-compose.yml
• Out of memory: Aumenta memoria del container o del server
• Dipendenze mancanti: Verifica i servizi linkati

📊 Problemi Flow Editor

Flow non si esegue

Checklist:

1. ✅ Il flow è abilitato (toggle verde)?
2. ✅ Il trigger è configurato correttamente?
3. ✅ Tutti i nodi sono collegati?
4. ✅ Le credenziali nei nodi HTTP sono valide?

Debug:

1. Clicca 🔍 Esecuzioni nel flow
2. Trova l’ultima esecuzione fallita
3. Guarda quale nodo ha fallito e il messaggio di errore

”Invalid JSON” in nodo HTTP

Causa: Il body della richiesta non è JSON valido.

Soluzione:

// ✅ Corretto
{
  "name": "value",
  "count": 123
}

// ❌ Errato (virgole finali)
{
  "name": "value",
  "count": 123,
}

Webhook non riceve dati

Verifica:

1. L’URL del webhook è corretto?
2. Il servizio esterno sta inviando POST requests?
3. Il content-type è application/json?

Test manuale:

curl -X POST https://app.polipo.dev/api/webhook/TUO_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

🔔 Problemi Notifiche

Non ricevo email di alert

Checklist:

1. ✅ Email configurata in Impostazioni → Notifiche?
2. ✅ Alert abilitati per il tipo di evento?
3. ✅ Controlla cartella spam/junk
4. ✅ Email verificata (clicca link di conferma)?

Email arrivano in ritardo

Causa: Queue di email sovraccarica o problemi con il provider SMTP.

Soluzione: Se usi SMTP personalizzato, verifica le credenziali e i limiti di invio.

Webhook non viene chiamato

Verifica:

1. URL raggiungibile da Internet?
2. Certificato SSL valido?
3. Endpoint accetta POST?

Test:

# Simula una chiamata dal nostro server
curl -X POST https://tuo-webhook.com/endpoint \
  -H "Content-Type: application/json" \
  -d '{"event": "test", "data": {}}'

⚡ Performance

Dashboard lenta a caricare

Soluzioni:

1. Riduci il range temporale dei grafici (7 giorni invece di 30)
2. Filtra per cliente specifico
3. Pulisci cache browser (Ctrl+Shift+Del)
4. Disabilita estensioni browser pesanti

API timeout

Causa: Query complessa che supera il timeout.

Soluzioni:

1. Usa paginazione (?limit=50&offset=0)
2. Riduci il range date nelle query analytics
3. Per export grandi, usa Export Asincrono

🗄️ Database

”Database is locked” (SQLite)

Causa: Scrittura concorrente su SQLite.

Soluzioni:

# Riavvia il server
npm run server:restart

# In produzione, considera PostgreSQL

Dati non salvati

Verifica:

1. Controlla i log del server per errori
2. Verifica che il database abbia spazio disco
3. Controlla permessi sulla cartella data/

🐛 Bug Report

Se riscontri un bug:

1. Riproduci il problema e nota i passi esatti
2. Screenshot dell’errore (includi console browser)
3. Log del server se accessibile
4. Invia via pannello Feedback nell’app

Include queste informazioni:

• Browser e versione
• Sistema operativo
• URL della pagina
• Messaggio di errore
• Passi per riprodurre

🔧 Comandi Utili

# Verifica stato servizi
npm run test:quick

# Riavvia server
npm run server:restart

# Pulisci cache
npm run cache:clear

# Verifica database
npm run db:check

# Esporta logs
npm run logs:export

Non risolto? Contatta il supporto allegando:

• Screenshot dell’errore
• Log della console browser (F12 → Console)
• Passi per riprodurre il problema