Dépannage

Problème → cause → solution. Dépannage courant pour les apps BPM.

1. bpm : command not found après pip install

Cause — Le script console bpm n'est pas dans le PATH (venv non activé ou pip install sans -e .).

Solution — Activer l'environnement virtuel : source .venv/bin/activate (Linux/macOS) ou .venv\Scripts\activate (Windows). Ou lancer explicitement : python -m bpm.cli run app.py.

2. Port déjà utilisé au lancement

Cause — Un autre processus utilise le port par défaut (8501).

Solution — Changer le port : bpm run app.py --port 8502 ou python -m bpm.cli run app.py --port 8502.

3. L'app se recharge entièrement à chaque clic

Cause — Comportement actuel : chaque interaction déclenche un re-run complet du script (comme Streamlit).

Solution — C'est normal pour l'instant. La réactivité granulaire (mise à jour ciblée sans re-run) est prévue (WebSocket/SSE) — voir Ce qu'il reste à faire.

4. Les refs réactives ne se mettent pas à jour

Cause — Les refs (bpm.ref) et la mise à jour ciblée ne sont pas encore implémentées côté serveur Python / protocole.

Solution — Utiliser bpm.session_state pour persister l'état entre les runs. Les refs seront documentées quand le support sera en place.

5. Erreur Nginx 502 Bad Gateway

Cause — Nginx ne peut pas joindre le serveur BPM (processus arrêté, mauvais port, ou BPM à l'écoute sur 127.0.0.1 uniquement).

Solution — Vérifier que le service BPM tourne : systemctl status blueprint-modular. Vérifier que proxy_pass pointe vers le bon port (ex. http://127.0.0.1:8501). Vérifier les logs Nginx et le journal systemd du service.

6. SSL : certificat expiré ou non reconnu

Cause — Certificat Let's Encrypt expiré ou renouvellement Certbot non configuré.

Solution — Renouveler : certbot renew. Vérifier la tâche cron ou systemd timer pour le renouvellement automatique. Vérifier que le navigateur fait confiance au certificat (pas d'auto-signé en prod sans import).

7. ModuleNotFoundError: No module named 'bpm'

Cause — Python s'exécute dans un environnement où le package BPM n'est pas installé (autre venv, autre interpréteur).

Solution — Installer le package : pip install blueprint-modular (PyPI). Si vous contribuez au dépôt : pip install -e . depuis la racine du repo (Blueprint-Modular/blueprint-modular). Vérifier avec python -c "import bpm; print(bpm.__file__)".