Aller au contenu

Dépannage

Pour toute panne, commencez par deux vérifications :

  1. l’état des conteneurs : docker compose -f docker-compose.yml ps ;
  2. le journal du service en cause : docker compose -f docker-compose.yml logs --tail=200 api (ou web, postgres).

Si l’application s’ouvre, Paramètres > À propos / Système et sa section Santé de l’instance donnent souvent la réponse (voir Surveillance et santé).

Symptôme Cause probable et solution
POSTGRES_PASSWORD is required (ou une autre variable) Variable absente de .env ou des variables de la stack. Voir Variables d’environnement.
pull access denied, unauthorized Le serveur n’est pas connecté à ghcr.io, ou le jeton n’a pas le droit read:packages.
port is already allocated Un autre programme utilise le port 3000, 4000, 5432 ou 3080. Changez WEB_PORT, API_PORT, POSTGRES_PORT ou DOCS_PORT.
web reste en attente Il attend que api soit en bonne santé : regardez le journal de api.
  • password authentication failed : POSTGRES_PASSWORD a changé après la création de la base. PostgreSQL garde le mot de passe d’origine : remettez l’ancien, ou changez-le dans la base (ALTER USER kiwidesk PASSWORD '...') avant de modifier .env.
  • Erreur pendant Applying database migrations... : une migration a échoué (disque plein, base restaurée d’une version plus récente). Lisez le message, libérez de l’espace si besoin, ou restaurez la sauvegarde d’avant la mise à jour (Mises à jour et migrations).
  • Erreur sur ENCRYPTION_KEY : la clé doit faire 32 octets encodés en base64. Une clé CHANGE-ME ou tronquée est refusée.
  • SEED_ADMIN_PASSWORD does not satisfy the password policy : mot de passe trop faible ; videz la variable pour qu’un mot de passe soit généré.
  • On revient sans cesse à la page de connexion : COOKIE_SECURE=true alors que le site est en HTTP, ou APP_PUBLIC_URL ne correspond pas à l’adresse utilisée.
  • « Trop de tentatives » : la limite de connexions par adresse est atteinte. Patientez une minute. Si toute l’équipe est bloquée en même temps, toutes les connexions semblent venir de la même adresse : réglez WEB_TRUSTED_PROXIES (Reverse proxy et HTTPS).
  • Compte verrouillé : trop de mots de passe faux sur ce compte. Il se déverrouille après la durée réglée dans Paramètres > Sécurité > Sessions & verrouillage, ou un administrateur le déverrouille depuis Paramètres > Utilisateurs.
  • Mot de passe du super administrateur perdu : si un autre super administrateur existe, il réinitialise le mot de passe depuis Paramètres > Utilisateurs. Sinon, vous pouvez créer un nouveau super administrateur : arrêtez l’API, mettez une nouvelle adresse dans SEED_ADMIN_EMAIL et redémarrez ; les données de départ créent ce compte s’il n’existe pas.
  • Heures décalées d’une ou deux heures sur des enregistrements anciens : la base tournait dans un autre fuseau horaire avant une mise à jour. La ligne Fuseau horaire de la base de données de la santé de l’instance doit être verte ; ne corrigez jamais à la main les dates des factures ou clôtures, elles font partie de leur signature.
  • Photos ou logos absents après une restauration ou un déplacement : le volume uploads n’a pas été restauré, ou ses fichiers n’appartiennent pas au bon utilisateur. Voir Sauvegarde et restauration.
  • Codes de déverrouillage illisibles : ENCRYPTION_KEY n’est pas celle qui les a chiffrés. Remettez la bonne clé ; ne la remplacez que par la rotation de clé.

Voir Dépannage du Bridge.

Les notifications, la messagerie et l’écran client se mettent à jour sans recharger la page. Dans Paramètres > À propos / Système, le bloc État des WebSockets & Temps réel doit indiquer Connecté ; Tester le ping WebSocket mesure l’aller-retour. Si l’état reste déconnecté derrière un reverse proxy, vérifiez que celui-ci ne coupe pas les requêtes longues (proxy_read_timeout, proxy_buffering off avec nginx).

Avant de signaler un problème, notez la version (Paramètres > À propos / Système), ce que vous faisiez, le message affiché et les lignes du journal de l’API au même moment. Retirez des journaux toute adresse e-mail, numéro de téléphone ou mot de passe.