Docs

Dépannage

Problèmes courants

L’agent ne démarre pas

Symptôme : fenwave service start ou fenwave service run échoue.

Causes possibles :

Cause Solution
Non connecté Exécuter fenwave login
Session expirée Exécuter fenwave login pour se ré-authentifier
Appareil non enregistré Exécuter fenwave init ou fenwave register
Docker non démarré Démarrer le daemon Docker (exécuter systemctl start docker)
Port déjà utilisé Utiliser --port <port> pour spécifier un autre port, ou arrêter le processus utilisant le port par défaut
Fichier de verrouillage obsolète L’agent détecte et nettoie automatiquement les verrouillages obsolètes. Si le problème persiste, supprimer ~/.fenwave/daemon/agent.lock

Impossible de se connecter

Symptôme : fenwave login ouvre le navigateur mais l’authentification échoue ou expire.

Vérifications :

  1. Le backend Fenwave IDP est-il en cours d’exécution et accessible ? 
    curl -s <backend-url>
  2. L’URL frontend est-elle correcte ? 
    fenwave config show
  3. Le port de loopback (49152–49251) est-il bloqué par un pare-feu ?
  4. Le login a-t-il expiré (par défaut : 60 secondes) ? Réessayez — le navigateur a peut-être été lent à charger.

Le tableau de bord DevApp ne se charge pas

Symptôme : L’agent démarre mais http://localhost:3003 n’affiche rien.

Vérifications :

  1. Le conteneur DevApp est-il en cours d’exécution ? 
    fenwave containers
  2. Docker est-il en cours d’exécution ? 
    docker ps
  3. Le port du conteneur est-il correct ? 
    fenwave config show
  4. Consulter les logs du conteneur pour les erreurs : 
    fenwave local-env --logs

Connexion WebSocket échouée

Symptôme : Le tableau de bord DevApp se charge mais affiche “Agent Disconnected” ou ne peut pas effectuer d’opérations.

Vérifications :

  1. L’agent est-il toujours en cours d’exécution ? 
    fenwave service status
  2. Le port WebSocket est-il accessible ? 
    fenwave config show    # Vérifier la valeur wsPort
  3. Vérifier si le fichier ws-token existe : 
    ls ~/.fenwave/ws-token
  4. Redémarrer l’agent pour régénérer le token : 
    fenwave service restart

Échec de l’enregistrement

Symptôme : fenwave init ou fenwave register échoue.

Causes possibles :

Cause Solution
Token invalide ou expiré Générer un nouveau token depuis l’IDP (valide 7 jours)
Token déjà utilisé Chaque token est à usage unique ; en générer un nouveau
Backend inaccessible Vérifier la valeur --backend-url et la connectivité réseau
Appareil déjà enregistré Utiliser fenwave rotate-credentials pour rafraîchir, ou fenwave uninstall puis ré-enregistrer

Erreurs de permissions lors de l’installation

Symptôme : npm install -g échoue avec EACCES ou permission refusée.

Solutions (choisir une) :

  1. Installer nvm (recommandé) : 
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm use 20
  2. Changer le préfixe npm : 
    mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
  3. Utiliser sudo (non recommandé) : 
    sudo npm install -g @fenwave/agent

Mode debug

Pour des logs détaillés, activer le mode debug :

# Via le flag CLI
fenwave service run --debug

# Via une variable d'environnement
DEBUG=true fenwave service start
FW_VERBOSE=true fenwave service start

Le mode debug affiche des informations supplémentaires sur :

  • Les requêtes HTTP vers le backend
  • Le routage des messages WebSocket
  • Les vérifications de validation de session

Réinitialisation complète

Si tout échoue, vous pouvez effectuer une réinitialisation complète :

# 1. Arrêter l'agent
fenwave service stop

# 2. Supprimer toutes les données de l'agent
fenwave uninstall

# 3. Relancer la configuration
fenwave init --token <nouveau-token> --backend-url <url>

# 4. Se connecter
fenwave login

# 5. Démarrer l'agent
fenwave service start

fenwave uninstall supprime toutes les données locales y compris les identifiants d’appareil, la session et la configuration. Vous aurez besoin d’un nouveau token d’enregistrement pour reconfigurer.