Aller au contenu principal

Dépannage

Liste des erreurs courantes rencontrées en développement et en production, avec leurs solutions.

Backend — démarrage​

Error: P1000: Authentication failed against database server​

L'API ne parvient pas à se connecter à PostgreSQL.

Causes possibles

  • DATABASE_URL incorrect dans apps/api/.env
  • L'utilisateur Postgres n'existe pas, ou son mot de passe est faux
  • Le conteneur Postgres n'est pas démarré

Solution

# Vérifier que Postgres est joignable
docker ps | grep postgres
psql -h localhost -U mombiz -d mombiz_dev -c "SELECT 1"

# Si l'utilisateur n'existe pas
docker exec -it dev-postgres psql -U dev -d postgres \
  -c "CREATE USER mombiz WITH PASSWORD 'mombiz-dev' CREATEDB;"

Error: P1001: Can't reach database server at localhost:5432 (Windows + WSL)​

Postgres tourne dans un conteneur Docker à l'intérieur de WSL, mais Prisma (côté Windows) n'atteint pas localhost:5432.

Cause : sous Windows, localhost résout d'abord en IPv6 (::1), or le port publié par Docker-dans-WSL n'écoute qu'en IPv4. Diagnostic :

Test-NetConnection localhost -Port 5432
# WARNING: TCP connect to (::1 : 5432) failed   ← IPv6 KO
# TcpTestSucceeded : True  (sur 127.0.0.1)       ← IPv4 OK

Solution : forcer l'IPv4 dans apps/api/.env — utiliser 127.0.0.1 au lieu de localhost (c'est désormais le défaut du .env.example) :

(Get-Content apps\api\.env) -replace 'localhost:5432','127.0.0.1:5432' | Set-Content apps\api\.env

Prérequis réseau : WSL2 en mode mirrored ([wsl2]\nnetworkingMode=mirrored dans C:\Users\<toi>\.wslconfig + wsl --shutdown). cf. getting-started.

Error: P3014: Prisma Migrate could not create the shadow database​

Prisma ne peut pas créer la base shadow temporaire utilisée par migrate dev.

Solution : accorder le privilège CREATEDB à l'utilisateur applicatif.

docker exec -it dev-postgres psql -U dev -d postgres \
  -c "ALTER USER mombiz CREATEDB;"

Error: secretOrPrivateKey must have a value​

Le JWT_SECRET n'est pas défini dans l'environnement de l'API.

Solution

echo "JWT_SECRET=$(openssl rand -base64 48)" >> apps/api/.env

Error: PORT 3000 already in use​

Le port 3000 est déjà occupé (probablement par le site Docusaurus).

Solution

# Lancer la doc sur un autre port
npm start --workspace=@app/docs -- --port 4000

# Ou changer le port de l'API dans apps/api/.env
PORT=3001

Backend — runtime​

Tous les endpoints retournent 401 Unauthorized​

Causes possibles

  • Le token JWT est expiré (15 min de durée)
  • Le secret a changé (rotation, redémarrage)
  • L'horloge serveur est décalée

Solution

  • Côté frontend : déclencher un POST /auth/refresh pour obtenir un nouveau couple
  • Si le refresh échoue lui aussi, demander à l'utilisateur de se reconnecter
  • Vérifier date côté serveur ; synchroniser avec ntpd si décalage > 30 s

Un endpoint retourne 403 Forbidden pour un user admin​

Causes possibles

  • Le rôle dans le JWT n'est pas ADMIN (vérifier decoded.role dans le token)
  • L'endpoint a @Roles('TEACHER') au lieu de @Roles('ADMIN', 'TEACHER')
  • L'isolation par propriété bloque (le service filtre where: { teacherId: user.sub } alors qu'un admin devrait avoir un bypass)

Solution : tracer le decorator @Roles du controller concerné, et inspecter la condition where du service. Pour les services qui doivent autoriser admin, le pattern est :

const isAdmin = user.role === 'ADMIN';
return this.prisma.course.findMany({
  where: isAdmin ? {} : { teacherId: user.sub },
});

Erreur Prisma Unknown arg​

Cause : le client Prisma n'a pas été régénéré après un changement de schema.prisma.

Solution

npm --workspace apps/api exec prisma generate
# Puis redémarrer l'API

Frontend — dev​

Cannot find module @rollup/rollup-win32-x64-msvc / lightningcss.win32-x64-msvc.node (Windows)​

Corrigé à la racine (commit e5e5b7a) : les binaires natifs win32+linux de Rollup, Tailwind oxide, lightningcss et esbuild sont épinglés en optionalDependencies dans le package.json racine, donc le package-lock.json les inscrit complètement. Installe avec npm ci et tout se pose. Cette section reste pour mémoire / si un nouveau natif apparaît.

Au démarrage de dev:frontend, Vite (ou Rollup) échoue car un paquet natif ou une dépendance transitive manque de node_modules, alors que npm install n'a affiché aucune erreur.

Cause racine : le package-lock.json est généré sous Linux ; pour les binaires natifs (*-win32-x64-msvc), npm n'y inscrit pas d'entrée installable (resolved+integrity) → npm ci ne peut pas les poser sous Windows (bug npm #4828). La parade : épingler ces natifs en optionalDependencies racine (déjà fait). Si un nouveau natif manque, ajouter <paquet>-win32-x64-msvc + -linux-x64-gnu/-musl au même bloc (version = celle de la lib parente), relancer npm install pour régénérer le lock, committer.

Cause : npm 11.x casse l'arbre de dépendances des workspaces — il pose les paquets directs (ex. @tailwindcss/vite sous apps/frontend-*/node_modules) sans installer leurs dépendances transitives (@tailwindcss/node, @rollup/* natifs) ni les hoister à la racine. Le package-lock.json du repo est généré avec npm 10 (cf. engines : npm >=10).

Diagnostic — la racine est vide alors qu'elle devrait contenir ces paquets :

Get-ChildItem node_modules\@tailwindcss   # doit lister : node, oxide, oxide-win32-x64-msvc, vite
Get-ChildItem node_modules\@rollup        # doit contenir rollup-win32-x64-msvc
npm -v                                     # si 11.x → c'est la cause

Solution : repasser sur npm 10 puis réinstaller proprement.

npm install -g npm@10.9.2
npm -v                                # doit afficher 10.x

taskkill /F /IM node.exe 2>$null      # libère les handles (moteur Prisma, etc.)
Remove-Item -Recurse -Force node_modules
Remove-Item -Force package-lock.json
npm install

# Vérifier (les deux doivent renvoyer True) :
Test-Path node_modules\@tailwindcss\node
Test-Path node_modules\@rollup\rollup-win32-x64-msvc

Rester sur npm 10 sur cette machine. Pièges voisins rencontrés sous Windows : EPERM unlink … query_engine-windows.dll.node (un process Node garde le moteur Prisma ouvert → taskkill /F /IM node.exe avant de réinstaller) et le bug npm des deps optionnelles (#4828, corrigé par le même nuke + réinstall).

Sous Windows, préférer npm ci à npm install. Chaque npm install mute l'arbre et redrop le natif rollup win32 (bug #4828) → l'erreur revient. npm ci fait une install propre et déterministe depuis le package-lock.json (qui contient déjà les natifs win32) et n'a pas ce souci. Toujours taskkill /F /IM node.exe avant, pour éviter l'EPERM du moteur Prisma.

Page blanche au chargement​

Causes possibles

  • Erreur JS non catchée (vérifier la console)
  • L'API n'est pas joignable (CORS, port, URL)

Solution

# Vérifier que l'API tourne
curl http://localhost:3000/api/v1/health

# Si l'URL n'est pas la bonne, dans le .env de l'app concernée
# (apps/frontend-public/.env, apps/frontend-learner/.env, ...) :
VITE_API_URL=http://localhost:3000/api/v1

CORS error sur les requêtes API​

Cause : l'API n'autorise pas l'origine du frontend.

Solution : vérifier la whitelist CORS dans apps/api/src/main.ts. Doit inclure http://localhost:5173 en dev.

Module not found: @app/contracts​

Cause : le package contracts n'est pas compilé.

Solution

npm run build:contracts

Le predev:api et prebuild:api le font automatiquement, mais le frontend ne déclenche pas cette précondition.

Migrations Prisma​

Migration créée en local mais pas appliquée en prod​

Cause : prisma migrate dev modifie la DB locale et écrit le fichier dans prisma/migrations/. Si le commit n'inclut pas le fichier de migration, la prod ne saura pas la rejouer.

Solution

git status apps/api/prisma/migrations/
# S'assurer que le dossier de la migration est commité
git add apps/api/prisma/migrations/<timestamp>_<name>/

Conflit lors d'un merge sur le dossier migrations/​

Cause : deux branches ont créé des migrations en parallèle.

Solution : la migration la plus tardive doit être renommée (timestamp suivant) et son SQL ajusté pour partir de l'état laissé par la première. Prisma ne fait pas de re-tri automatique.

Documentation Docusaurus​

Can't render static file for pathname "/...": ReferenceError: id is not defined​

Cause : un template literal ${...} dans un fichier .md est interprété par MDX comme une expression JSX.

Solution : déplacer le code dans un block code triple-backtick, ou échapper le $ :

<!-- Cassé -->
Voir `prisma.$queryRaw\`SELECT ${id}\``

<!-- OK -->
Voir le snippet :

​```ts
prisma.$queryRaw`SELECT ${userId}`
​```

Build échoue avec Broken anchor​

Cause : un lien [texte](./fichier#section) pointe vers une section qui n'existe pas (typo dans le titre).

Solution : vérifier l'orthographe du titre cible et son slug Docusaurus (les espaces deviennent -, les accents disparaissent).

Production​

L'API rejette tous les nouveaux JWT après un déploiement​

Cause : le JWT_SECRET a changé entre les versions.

Solution prévue : tous les utilisateurs doivent se reconnecter. Si la rotation est intentionnelle, prévoir une fenêtre de tolérance (deux secrets acceptés en parallèle pendant 24 h) — feature à implémenter en v1.1.

Backups quotidiens absents​

Solution

  • Vérifier le cron du serveur backup
  • Vérifier l'espace disque restant (df -h)
  • Tester manuellement pg_dump pour valider la connectivité

Demander de l'aide​

Si un problème persiste :

  1. Lire l'historique GitLab du domaine concerné — souvent un bug similaire a déjà été corrigé
  2. Inspecter les logs applicatifs Nest (niveau ERROR)
  3. Reproduire en local avec une base seedée propre (npm run seed --workspace apps/api)
  4. Ouvrir une issue GitLab avec les étapes de reproduction et le payload exact qui échoue