Skip to content

Troubleshooting

Jump to bottom
Andrea Bozzo edited this page Jul 20, 2025 · 1 revision

Troubleshooting - Osservatorio ISTAT

🚨 Problemi Comuni e Soluzioni

🐍 Problemi Python

ImportError: No module named 'src'

Problema: Moduli locali non trovati Soluzione:

# Aggiungi al PYTHONPATH
export PYTHONPATH=$PYTHONPATH:$(pwd)  # Linux/Mac
set PYTHONPATH=%PYTHONPATH%;%CD%      # Windows

# O esegui dalla root del progetto
python -m src.api.istat_api

ModuleNotFoundError: pandas/numpy

Problema: Dipendenze non installate correttamente Soluzione:

# Reinstalla dipendenze
pip install --upgrade pip
pip install -r requirements.txt --force-reinstall

# Su Windows con errori di compilazione
pip install --only-binary=all pandas numpy

Python version mismatch

Problema: Versione Python non supportata Soluzione:

# Verifica versione (deve essere 3.13.3)
python --version

# Usa pyenv per gestire versioni
pyenv install 3.13.3
pyenv local 3.13.3

🌐 Problemi API

ISTAT API Timeout/Connection Error

Problema: API ISTAT non risponde Diagnosi:

python src/api/istat_api.py

Soluzioni:

  • Verifica connessione internet
  • Rate limiting: attendi 1-2 minuti tra chiamate
  • Usa dati cached: controlla data/cache/
  • Fallback a dati mock se necessario

PowerBI Authentication Failed

Problema: Errore autenticazione PowerBI Diagnosi:

python src/api/powerbi_api.py

Soluzioni:

# Rigenera token
python scripts/setup_powerbi_azure.py

# Verifica credenziali in .env
cat .env | grep POWERBI

# Reset cache autenticazione
rm -rf ~/.powerbi_cache

Tableau Connection Issues

Problema: Connessione Tableau fallisce Diagnosi:

python src/scrapers/tableau_scraper.py

Soluzioni:

  • Verifica tableau_config.json
  • Controlla credenziali OAuth
  • Testa connessione diretta al server

📊 Problemi Dashboard

Streamlit Won't Start

Problema: Dashboard non si avvia Diagnosi:

streamlit --version  # Deve essere 1.45.0+
streamlit run dashboard/app.py --logger.level=debug

Soluzioni:

# Reinstalla Streamlit
pip uninstall streamlit
pip install streamlit==1.45.0

# Porta già in uso
streamlit run dashboard/app.py --server.port=8502

# Reset config Streamlit
rm -rf ~/.streamlit

Dashboard Data Loading Errors

Problema: Dati non si caricano nella dashboard Diagnosi: Controlla logs in console browser e terminal Soluzioni:

  • Verifica cache: ls data/cache/
  • Testa API ISTAT: python src/api/istat_api.py
  • Genera dati mock: python scripts/generate_test_data.py
  • Restart dashboard con cache pulita

Memory Errors in Dashboard

Problema: Dashboard crash per memoria insufficiente Soluzioni:

# Aumenta memoria Streamlit
streamlit run dashboard/app.py --server.maxUploadSize=1000

# Processa meno dati
# Modifica dashboard/data_loader.py per limitare datasets

🧪 Problemi Testing

Tests Failing Locally

Problema: Test falliscono in locale ma passano in CI Diagnosi:

pytest tests/unit/ -v --tb=long
pytest --collect-only  # Verifica 292 tests

Soluzioni:

# Pulisci cache pytest
rm -rf .pytest_cache __pycache__ src/__pycache__

# Reinstalla dipendenze test
pip install -r requirements-dev.txt

# Test specifici
pytest tests/unit/test_config.py -v

Coverage Issues

Problema: Coverage basso o errori report Soluzioni:

# Rigenera coverage
rm -rf htmlcov/ .coverage
pytest --cov=src tests/ --cov-report=html

# Test coverage specifici
pytest --cov=src.utils tests/unit/test_config.py --cov-report=term

CI/CD Test Failures

Problema: GitHub Actions fallisce Diagnosi: Verifica logs in GitHub Actions Soluzioni:

# Test CI locale
python scripts/test_ci.py --strategy minimal

# Verifica workflow
cat .github/workflows/test.yml

# Test generazione dati
python scripts/generate_test_data.py

📁 Problemi File System

Permission Denied Errors

Problema: Errori di permessi su file/directory Soluzioni:

# Linux/Mac
chmod +x scripts/*.py
chmod -R 755 data/

# Windows (run as administrator)
icacls data /grant Users:F /T

Temp Files Not Cleaned

Problema: File temporanei accumulati Soluzioni:

# Cleanup manuale
python scripts/cleanup_temp_files.py

# Statistiche temp files
python scripts/cleanup_temp_files.py --stats

# Cleanup forzato
python scripts/cleanup_temp_files.py --max-age 1

File Encoding Issues

Problema: Errori encoding su Windows Soluzioni:

# Set UTF-8 globalmente
chcp 65001
set PYTHONIOENCODING=utf-8

# Nel codice Python
open(file, encoding='utf-8')

🔒 Problemi Sicurezza

Rate Limiting Too Strict

Problema: Rate limiting blocca sviluppo Soluzione: Modifica src/utils/security_enhanced.py:

# Aumenta limiti per dev locale
ISTAT_RATE_LIMIT = 1000  # Default: 50
POWERBI_RATE_LIMIT = 1000  # Default: 100

Security Scan False Positives

Problema: Bandit/Safety report falsi positivi Soluzioni:

# Ignora warnings specifici
bandit -r src/ -s B101,B601

# Skip security check temporaneo
pre-commit run --all-files --skip bandit

💾 Problemi Performance

Slow Data Processing

Problema: Conversione dati molto lenta Soluzioni:

  • Processa file più piccoli
  • Usa cache quando possibile
  • Ottimizza query ISTAT API
  • Implementa processing parallelo

High Memory Usage

Problema: Uso memoria eccessivo Diagnosi:

# Monitor memoria
python -c "
import psutil
print(f'RAM: {psutil.virtual_memory().percent}%')
print(f'Available: {psutil.virtual_memory().available // 1024**3}GB')
"

Soluzioni:

  • Processa dati in batch
  • Usa generatori invece di liste
  • Implementa lazy loading
  • Aumenta swap/virtual memory

🛠️ Strumenti Debug

Debug Generale

# Enable debug logging
export LOG_LEVEL=DEBUG

# Debug con pdb
python -m pdb src/api/istat_api.py

# Profile performance
python -m cProfile -o profile.stats src/api/istat_api.py

Network Debug

# Test connettività ISTAT
curl -I http://sdmx.istat.it/SDMXWS/rest/

# Test con verbose
python src/api/istat_api.py --verbose

# Proxy settings se necessario
export HTTPS_PROXY=your-proxy
export HTTP_PROXY=your-proxy

Database Debug (se applicabile)

# Test DuckDB connection
python -c "import duckdb; print(duckdb.sql('SELECT 1'))"

# Check data files
ls -la data/processed/

📋 Checklist Debug

Prima di aprire issue, verifica:

  • Python version 3.13.3
  • Virtual environment attivo
  • Dipendenze aggiornate: pip list
  • Test base passano: pytest tests/unit/test_config.py
  • API ISTAT accessibile: python src/api/istat_api.py
  • Cache pulita: rm -rf data/cache/*
  • Temp files puliti: python scripts/cleanup_temp_files.py
  • Logs controllati in logs/ o console
  • Variables d'ambiente corrette: env | grep -E "(PYTHON|LOG|ISTAT)"

📧 Escalation

Se il problema persiste:

  1. GitHub Issues: Crea issue con template bug report
  2. Discussions: Usa GitHub Discussions per domande generali
  3. Logs: Includi sempre logs completi e stack trace
  4. Environment: Specifica OS, Python version, dipendenze

Template Issue Bug

**Describe the bug**
Descrizione chiara del problema

**To Reproduce**
Steps per riprodurre:
1. ...
2. ...

**Expected behavior**
Comportamento atteso

**Environment:**
- OS: [Windows 10/11, Ubuntu 20.04, etc.]
- Python version: [3.13.3]
- Streamlit version: [1.45.0]

**Additional context**
Stack trace, logs, screenshots
Clone this wiki locally