Dépannage courant

Cette fiche compile les symptômes les plus fréquents rencontrés au démarrage, en base de données, sur les emails, sur la connexion et sur les uploads — avec, pour chacun, la cause la plus probable et l'action à mener. Elle ne couvre pas le dépannage propre à un fournisseur SMTP (Gmail, Brevo, OVH…) : voir Fournisseurs SMTP pour ces cas-là.

Où trouver les logs

La plupart des symptômes ci-dessous s'expliquent par une ligne d'erreur explicite dans les journaux applicatifs — c'est le premier réflexe avant toute autre vérification.

• Développement local : npm run dev affiche dans le même terminal les journaux des trois processus (SHARED, CLIENT, SERVER), préfixés par leur nom respectif.

• Docker (installation manuelle) :

  docker logs -f timepick

  Remplacer timepick par le nom donné au conteneur avec docker run --name (voir Installation en production (Docker)).

• Coolify : sur la page de l'application TimePick, onglet Build Logs pendant un déploiement (erreurs de compilation) et onglet Application Logs (erreurs au démarrage ou en cours d'exécution — chercher les lignes [prepare-db] puis [migrate] juste après un déploiement).

Vérifier l'état du serveur avant de creuser

Deux endpoints de santé permettent un premier diagnostic sans consulter les logs :

• GET /health (public, sans authentification) — statut binaire ok/degraded, incluant l'état du SMTP. Voir API — Endpoint de santé.
• GET /api/admin/health (authentifié, rôle admin — en-tête Authorization: Bearer <token>) — statut détaillé incluant la base de données.

curl https://timepick.example.org/health

Réponse sur une instance saine :

{ "status": "ok", "timestamp": "2026-07-13T08:00:00.000Z", "services": { "smtp": "ok" } }

Réponse quand le SMTP n'est pas (ou plus) fonctionnel — le code HTTP reste 200, seul le champ status change :

{ "status": "degraded", "timestamp": "2026-07-13T08:00:00.000Z", "services": { "smtp": "degraded" } }

Un status: "degraded" n'empêche pas l'application de répondre

Le SPA, l'authentification déjà établie et les créneaux restent utilisables : seuls les envois d'email échoueront tant que le SMTP n'est pas rétabli. C'est volontaire — un healthcheck d'orchestrateur configuré strictement sur ce champ redémarrerait le conteneur en boucle pour un simple problème SMTP, sans rien résoudre.

Pour une inspection directe de la base (par exemple confirmer qu'un administrateur existe, ou consulter les dernières migrations appliquées), voir Accès à la base de données en production et les requêtes de diagnostic en lecture seule de Modèle de données.

Tableau de dépannage

Thème	Symptôme	Cause probable	Action
Démarrage	Conteneur ne démarre pas / redémarre en boucle	Bootstrap ou migrations en échec au démarrage, ou DATABASE_URL incorrecte / base injoignable	Consulter les logs applicatifs (voir ci-dessus), chercher une erreur après la ligne [prepare-db] ou [migrate] ; vérifier que DATABASE_URL pointe vers une base PostgreSQL démarrée et accessible depuis le conteneur
Démarrage	Le build de l'image Docker échoue sur sharp ou bcrypt	Modules natifs non compilés pour l'architecture cible de l'image	Vérifier que l'étape de build utilise l'image node:22-bookworm-slim du Dockerfile fourni, sans modification de la base — voir Installation en production (Docker)
Démarrage	502 Bad Gateway après un déploiement	Mauvais port exposé côté conteneur, ou healthcheck mal ciblé	Vérifier que le conteneur écoute sur PORT=3000 (valeur par défaut) et que le healthcheck de l'orchestrateur pointe bien vers GET /health sur ce port
Démarrage	GET /health répond 200 avec "status":"degraded"	Aucune configuration SMTP fonctionnelle en base (services.smtp en échec)	Configurer ou corriger le serveur d'email depuis Paramètres → Serveur d'email — voir Fournisseurs SMTP
Base de données	permission denied to create extension (lors de npm run init-db, ou au tout premier démarrage)	Le rôle PostgreSQL désigné par DATABASE_URL n'a pas les droits nécessaires pour créer l'extension uuid-ossp	Accorder temporairement les droits superutilisateur (psql -c "ALTER USER <utilisateur> SUPERUSER"), ou faire préinstaller l'extension par un administrateur PostgreSQL — voir Installation locale
Base de données	« Une création d'administrateur est déjà en cours » au clic sur le lien d'amorçage	Verrou PostgreSQL (advisory lock) actif : une autre création du premier administrateur est en cours au même instant (double clic, deux onglets, deux personnes)	Attendre quelques secondes et recliquer le lien — le verrou se libère automatiquement à la fin de la transaction. Voir Configuration initiale
Base de données	Erreur SQL évoquant date_trunc à 3 arguments (tableau de bord)	Version de PostgreSQL antérieure à 16	Migrer vers PostgreSQL 16 ou supérieur (17 recommandé) — voir Prérequis
Base de données	Le serveur refuse de démarrer juste après une mise à jour, erreur liée à un modèle d'email manquant	Migrations non appliquées avant le redémarrage : une migration qui étend le catalogue de modèles d'email doit s'exécuter avant que le nouveau code ne démarre	Appliquer les migrations en attente (npm run migrate, ou automatique au démarrage du conteneur) avant de redémarrer le serveur — voir Mise à jour
Emails	Magic link (connexion ou invitation) jamais reçu, en production	Configuration SMTP absente, incorrecte ou fournisseur indisponible	Consulter les logs serveur pour une erreur SMTP explicite ; tester la configuration depuis Paramètres → Serveur d'email (bouton Tester la connexion) — voir Fournisseurs SMTP et Délivrabilité email
Emails	Magic link jamais reçu, en développement local	Aucun serveur SMTP réel configuré — comportement attendu en développement	Utiliser MailHog : port 1025 pour l'envoi (configuration SMTP de l'assistant ou de l'application), interface http://localhost:8025 pour consulter les emails interceptés — voir Fournisseurs SMTP — MailHog
Emails	Email reçu mais classé en spam	Absence d'enregistrements SPF/DKIM/DMARC pour le domaine d'expédition	Voir Délivrabilité email
Emails	Les variables SMTP_* modifiées dans l'environnement (Coolify, .env) restent sans effet	Ces variables ne servent qu'au provisionnement initial en base ; une fois la configuration copiée au premier démarrage, le runtime lit exclusivement la base de données	Modifier la configuration depuis Paramètres → Serveur d'email, dans l'application — jamais dans les variables d'environnement après le premier démarrage. Voir Variables d'environnement
Connexion	Le frontend affiche des erreurs réseau, ou appelle un mauvais domaine d'API	VITE_API_URL incorrecte : c'est une variable figée au moment du build, non modifiable au runtime une fois l'image construite	Reconstruire l'image avec la bonne valeur (docker build --build-arg VITE_API_URL=...) et redéployer — voir Installation en production (Docker)
Connexion	La page /setup n'apparaît pas, redirection directe vers /login	Un administrateur existe déjà en base	Se connecter normalement, ou confirmer via une requête psql en lecture seule — voir Modèle de données
Connexion	Une session (admin ou membre) expire trop vite, ou au contraire trop tard	Durée de vie (TTL) mal ajustée dans les paramètres	Ajuster depuis Paramètres → Authentification — voir Paramètres in-app
Uploads	Images utilisées dans les emails (logo, illustrations) disparues après un redéploiement	Le volume /app/server/uploads n'était pas monté : ce chemin n'est pas persistant par défaut dans le conteneur	Configurer un volume persistant sur /app/server/uploads (onglet Storages dans Coolify, ou option -v en Docker) avant tout usage en production — voir Installation en production (Docker) — Volume persistant

Un symptôme absent de ce tableau ?

Commencer par les logs (section ci-dessus), puis par le healthcheck détaillé (GET /api/admin/health) : la plupart des pannes non listées ici se ramènent à une base de données injoignable, une configuration SMTP invalide, ou une variable de build (VITE_API_URL) désynchronisée d'un redéploiement récent.

Voir aussi

• Fournisseurs SMTP — dépannage propre à chaque fournisseur (Gmail, Brevo, OVH…)
• Délivrabilité email — spam, réputation d'envoi, SPF/DKIM/DMARC
• Sauvegarde et restauration — avant toute intervention manuelle en base
• Variables d'environnement — infrastructure vs réglages applicatifs
• Modèle de données — requêtes de diagnostic en lecture seule