Guide de Dépannage#

Ce guide répertorie les problèmes courants et leurs solutions.

Table des matières#

Problèmes Docker
Problèmes npm
Problèmes de tests
Problèmes de build
Problèmes de déploiement
Problèmes de serveur local
Problèmes Git
Problèmes de sécurité
Problèmes de performance

Problèmes Docker#

Container ne démarre pas#

Symptôme :

make up
# ERROR: Cannot start service dev: ...

Causes possibles :

Docker n'est pas démarré

# Vérifier
docker ps
# → Cannot connect to Docker daemon

# Solution : Démarrer Docker Desktop (macOS/Windows)
# Ou démarrer le daemon (Linux)
sudo systemctl start docker

Port déjà utilisé

# Vérifier les ports dans docker-compose.yml
# Modifier le port si nécessaire

Image corrompue

# Rebuild l'image
make down
docker compose build --no-cache
make up

Permissions (Linux uniquement)#

Symptôme :

make shell
# permission denied while trying to connect to the Docker daemon socket

Solution :

# Ajouter votre utilisateur au groupe docker
sudo usermod -aG docker $USER

# Se déconnecter/reconnecter
# Ou recharger le groupe
newgrp docker

# Vérifier
docker ps

Container tourne mais commandes échouent#

Symptôme :

make npm CMD="test"
# sh: npm: not found

Solution :

# Rebuild le container
make down
make init

Volumes ne se montent pas correctement#

Symptôme : Les modifications de fichiers locaux ne sont pas visibles dans le container

Solution :

# Vérifier le bind mount dans docker-compose.yml
# Redémarrer le container
make restart

# Si ça persiste (Windows/WSL)
# Vérifier les permissions et line endings
git config core.autocrlf false

Nettoyer complètement Docker#

Symptôme : Comportement bizarre, problèmes persistants

Solution :

# Arrêter tout
make down

# Supprimer volumes
docker volume prune

# Supprimer images
docker image prune -a

# Recommencer
make init

Problèmes npm#

Installation échoue#

Symptôme :

npm install
# ERR! code ERESOLVE

Solutions :

# 1. Nettoyer node_modules
rm -rf node_modules package-lock.json

# 2. Installer avec force
npm install --force

# 3. Ou ignorer conflicts
npm install --legacy-peer-deps

# 4. Vérifier la version Node.js
node --version  # Devrait être v20+ ou v25+

Package obsolète ou vulnérable#

Symptôme :

npm audit
# found 5 vulnerabilities (2 moderate, 3 high)

Solutions :

# 1. Mettre à jour automatiquement
npm audit fix

# 2. Forcer les mises à jour majeures
npm audit fix --force

# 3. Ignorer une vulnérabilité spécifique (temporaire)
npm audit --production  # Ignorer devDependencies

# 4. Mettre à jour un package spécifique
npm update <package-name>

# 5. Upgrade à la dernière version
npm install <package-name>@latest

Scripts npm échouent#

Symptôme :

npm run build
# Command not found: node

Solutions :

# Vérifier que vous êtes dans le container
make shell

# Ou utiliser make npm
make npm CMD="run build"

# Vérifier package.json
cat package.json | grep scripts

Problèmes de tests#

Tous les tests échouent#

Symptôme :

npm test
# FAIL lib/seeded-random.test.js
# Cannot find module 'jest'

Solutions :

# 1. Réinstaller les dépendances
npm ci

# 2. Nettoyer le cache Jest
npm test -- --clearCache

# 3. Vérifier la configuration Jest
cat jest.config.js

Tests passent localement mais échouent en CI#

Symptôme : Tests ✅ localement, ❌ dans GitHub Actions

Causes possibles :

Différences d'environnement

# Vérifier Node version
node --version  # En local
# vs version dans .github/workflows/ci.yml

Tests dépendent de l'ordre d'exécution

# Exécuter les tests en mode aléatoire
npm test -- --randomize

Tests dépendent de timings

// ❌ Mauvais : timeout trop court
setTimeout(() => expect(value).toBe(true), 10);

// ✅ Bon : utiliser fake timers
jest.useFakeTimers();

Coverage baisse#

Symptôme : Codecov reporte une baisse de coverage

Solutions :

# 1. Vérifier le coverage localement
npm run test:coverage

# 2. Voir les fichiers non couverts
open coverage/lcov-report/index.html

# 3. Ajouter des tests pour nouveau code
# Voir docs/TESTING_STRATEGY.md

Tests timeout#

Symptôme :

FAIL: Timeout - Async callback was not invoked within the 5000 ms timeout

Solutions :

// 1. Augmenter le timeout pour un test spécifique
test('long operation', async () => {
  // ...
}, 10000); // 10 secondes

// 2. Ou globalement dans jest.config.js
export default {
  testTimeout: 10000
};

// 3. Vérifier les promesses non résolues
// S'assurer que tous les async/await sont corrects

Problèmes de build#

Build échoue : Erreur JSON#

Symptôme :

npm run build
# SyntaxError: Unexpected token } in JSON

Solutions :

# 1. Trouver le fichier JSON invalide
# Vérifier tous les manifests
find . -name "*.json" -type f -not -path "./node_modules/*" | while read file; do
  echo "Checking $file"
  jq empty "$file" 2>&1 || echo "❌ Invalid: $file"
done

# 2. Valider avec jq
jq . tools/mon-tool/tool.json

# 3. Ou utiliser un validator en ligne
# https://jsonlint.com/

Build échoue : Fichier manquant#

Symptôme :

npm run build:catalogue
# Error: ENOENT: no such file or directory, open 'games/mon-jeu/game.json'

Solutions :

# 1. Vérifier que le fichier existe
ls -la games/mon-jeu/game.json

# 2. Vérifier les permissions
chmod 644 games/mon-jeu/game.json

# 3. Vérifier le .gitignore
# S'assurer que le fichier n'est pas ignoré
cat .gitignore

Catalogue vide après build#

Symptôme : data/catalogue.json contient []

Solutions :

# 1. Vérifier les manifests
ls -la tools/*/tool.json
ls -la games/*/game.json

# 2. Vérifier le format des manifests
cat tools/mon-tool/tool.json
# Doit contenir au minimum : id, title, description, type

# 3. Relancer le build avec logs
node src/scripts/build-catalogue.js

Build lent#

Symptôme : npm run build prend plusieurs minutes

Solutions :

# 1. Identifier le goulot
time npm run build:catalogue
time npm run build:parcours
time npm run build:bookmarks

# 2. Paralléliser (déjà fait dans package.json)
# Vérifier package.json :
# "build": "npm run build:catalogue && npm run build:parcours && ..."

# 3. Optimiser les scripts
# Éviter de relire les mêmes fichiers plusieurs fois

Problèmes de déploiement#

Workflow Deploy échoue#

Symptôme : GitHub Actions > Deploy to GitHub Pages ❌

Solutions :

Vérifier les logs du workflow

# GitHub Actions > Deploy to GitHub Pages > Run #123
# Cliquer sur le job en échec
# Lire les logs

Permissions GitHub Pages

# Aller dans Settings > Pages
# Source : GitHub Actions (pas "Deploy from branch")

Permissions du workflow

# Vérifier .github/workflows/deploy.yml
permissions:
  contents: read
  pages: write
  id-token: write

Site inaccessible après déploiement#

Symptôme : 404 sur https://z4ppy.github.io/playlab42/

Solutions :

# 1. Vérifier que le workflow est terminé
# GitHub Actions > Deploy to GitHub Pages > ✅

# 2. Attendre 1-2 minutes (propagation CDN)

# 3. Vider le cache navigateur
# Ctrl+Shift+R (Chrome/Firefox)
# Cmd+Shift+R (macOS)

# 4. Vérifier le statut GitHub Pages
# Settings > Pages > "Your site is live at..."

# 5. Tester en mode incognito

Fichiers manquants en production#

Symptôme : Fichiers visibles localement mais 404 en production

Causes :

Fichier dans .gitignore

# Vérifier
git ls-files | grep "mon-fichier.js"
# Si vide → fichier ignoré

# Solution : Retirer du .gitignore et commit
git add -f mon-fichier.js
git commit -m "fix: ajout fichier manquant"

Path absolu vs relatif

// ❌ Mauvais (chemin absolu)
fetch('/data/catalogue.json')

// ✅ Bon (chemin relatif)
fetch('./data/catalogue.json')

Fichier généré non committé

# data/catalogue.json est généré par le build
# Vérifier qu'il est bien créé dans le workflow
# .github/workflows/deploy.yml doit contenir :
# - run: npm run build

Rollback urgent#

Symptôme : Déploiement a introduit un bug critique

Solution rapide :

# Voir docs/DEPLOYMENT.md section "Rollback"

# TL;DR : Revert du commit
git log --oneline  # Identifier le commit problématique
git revert <commit-hash>
git push origin main  # Déclenche redéploiement automatique

Problèmes de serveur local#

Port 5242 déjà utilisé#

Symptôme :

make serve
# Error: listen EADDRINUSE: address already in use :::5242

Solutions :

# 1. Trouver le processus
lsof -i :5242
# ou (Linux)
netstat -tulpn | grep 5242

# 2. Tuer le processus
kill -9 <PID>

# 3. Ou utiliser un autre port
npx serve . -p 3000

CORS errors#

Symptôme : Console affiche CORS policy: No 'Access-Control-Allow-Origin' header

Solutions :

# 1. Utiliser le serveur avec CORS activé
npx serve . -p 5242 -C  # -C active CORS

# 2. Ou ajouter --cors au script package.json
# "serve": "npx serve . -p 5242 -C"

# 3. Pour développement : désactiver CORS dans le navigateur
# Chrome : --disable-web-security --user-data-dir=/tmp/chrome
# ⚠️ Seulement pour dev, jamais en production

Modifications pas visibles#

Symptôme : Éditer un fichier mais pas de changement dans le navigateur

Solutions :

# 1. Vider le cache navigateur
# Ctrl+Shift+R (hard reload)

# 2. Désactiver le cache en DevTools
# F12 > Network > Disable cache

# 3. Vérifier que le fichier est bien modifié
cat mon-fichier.js | head

# 4. Redémarrer le serveur
# Ctrl+C puis make serve

Page blanche (index.html)#

Symptôme : http://localhost:5242 affiche une page blanche

Solutions :

# 1. Vérifier la console navigateur (F12)
# Lire les erreurs JavaScript

# 2. Vérifier que index.html existe
ls -la index.html

# 3. Vérifier le contenu
cat index.html | head

# 4. Vérifier les imports JavaScript
# S'assurer que tous les <script src="..."> pointent vers des fichiers existants

Problèmes Git#

Conflicts lors du merge#

Symptôme :

git pull origin main
# CONFLICT (content): Merge conflict in file.js

Solutions :

# 1. Voir les fichiers en conflit
git status

# 2. Résoudre manuellement
# Ouvrir le fichier et chercher :
# <<<<<<< HEAD
# votre code
# =======
# code distant
# >>>>>>> branch-name

# 3. Éditer pour garder la bonne version

# 4. Marquer comme résolu
git add file.js

# 5. Terminer le merge
git commit

Push rejeté (non-fast-forward)#

Symptôme :

git push origin main
# error: failed to push some refs
# hint: Updates were rejected because the tip of your current branch is behind

Solutions :

# 1. Récupérer les changements distants
git pull origin main

# 2. Résoudre les conflits si nécessaire (voir ci-dessus)

# 3. Push à nouveau
git push origin main

# ⚠️ NE JAMAIS FAIRE : git push --force (sauf cas exceptionnel)

Commit sur mauvaise branche#

Symptôme : J'ai committé sur main au lieu de ma branche feature

Solutions :

# Option 1 : Déplacer le commit vers une nouvelle branche
git branch feature/ma-branche  # Crée la branche
git reset --hard HEAD~1        # Recule main d'un commit
git checkout feature/ma-branche

# Option 2 : Cherry-pick
git checkout -b feature/ma-branche
git cherry-pick <commit-hash>
git checkout main
git reset --hard HEAD~1

Fichier volumineux (>100MB)#

Symptôme :

git push
# error: GH001: Large files detected
# error: File big-file.zip is 150.00 MB; this exceeds GitHub's file size limit of 100.00 MB

Solutions :

# 1. Retirer le fichier du commit
git rm --cached big-file.zip
git commit --amend

# 2. Ajouter au .gitignore
echo "big-file.zip" >> .gitignore
git add .gitignore
git commit -m "chore: ignore large files"

# 3. Si fichier déjà dans l'historique (utiliser BFG Repo Cleaner)
# https://rtyley.github.io/bfg-repo-cleaner/

Problèmes de sécurité#

npm audit trouve des vulnérabilités#

Symptôme :

npm audit
# found 5 vulnerabilities (2 moderate, 3 high)

Solutions :

# 1. Mettre à jour automatiquement
npm audit fix

# 2. Forcer les mises à jour (breaking changes)
npm audit fix --force

# 3. Ignorer temporairement (devDependencies seulement)
npm audit --production

# 4. Voir détails
npm audit

# 5. Voir le workflow Security Audit dans GitHub Actions

GitLeaks détecte un secret#

Symptôme : Security Audit workflow échoue (GitLeaks)

Solutions :

# 1. Identifier le secret détecté
# Voir les logs GitHub Actions > Security Audit > gitleaks

# 2. Supprimer le secret du code
# Éditer le fichier et supprimer la clé

# 3. Commit
git add .
git commit -m "fix: remove leaked secret"

# 4. Révoquer le secret exposé
# Si API key : la régénérer sur le service
# Si password : le changer

# 5. Si secret dans l'historique Git
# Utiliser git-filter-repo ou BFG Repo Cleaner

ESLint security warnings#

Symptôme : Security Audit workflow rapporte des warnings ESLint

Solutions :

# 1. Voir les détails
make security-eslint

# 2. Corriger les problèmes
# Exemples courants :

# eval() détecté
# ❌ eval(userInput)
# ✅ Éviter eval, utiliser Function constructor si vraiment nécessaire

# innerHTML avec données non sanitisées
# ❌ element.innerHTML = userInput
# ✅ element.textContent = userInput

# RegExp non-littéral
# ❌ new RegExp(userInput)
# ✅ Valider userInput d'abord

Problèmes de performance#

Build très lent#

Symptôme : npm run build prend >30 secondes

Solutions :

# 1. Profiler
time npm run build:catalogue
time npm run build:parcours

# 2. Optimiser les scripts
# Éviter de lire les mêmes fichiers plusieurs fois
# Utiliser un cache si nécessaire

# 3. Vérifier le nombre de fichiers
find tools -name "*.json" | wc -l
find games -name "*.json" | wc -l

Tests très lents#

Symptôme : npm test prend >10 secondes

Solutions :

# 1. Exécuter en parallèle (par défaut avec Jest)
# Vérifier jest.config.js :
# maxWorkers: '50%'

# 2. Filtrer les tests
npm test -- seeded-random  # Seulement seeded-random.test.js

# 3. Utiliser mode watch
npm run test:watch

# 4. Désactiver coverage (plus rapide)
npm test -- --coverage=false

Serveur local lent#

Symptôme : http://localhost:5242 met du temps à charger

Solutions :

# 1. Vérifier le nombre de fichiers servis
find . -type f -not -path "./node_modules/*" | wc -l

# 2. Optimiser les assets
# Compresser les images (PNG → WebP, etc.)
# Minifier JS/CSS (en production)

# 3. Utiliser un autre serveur
npm install -g http-server
http-server . -p 5242 -c-1  # Pas de cache

Problèmes spécifiques#

Tic-Tac-Toe bot ne fonctionne pas#

Symptôme : Bot fait des moves invalides

Solutions :

# 1. Vérifier les logs console (F12)

# 2. Tester le moteur isolément
npm test -- tic-tac-toe

# 3. Vérifier l'implémentation du bot
cat games/tic-tac-toe/bot-minimax.js

# 4. Débugger avec console.log
# Ajouter des logs dans le bot

Parcours ne charge pas#

Symptôme : Parcours viewer affiche une erreur

Solutions :

# 1. Vérifier epic.json
jq . parcours/epics/mon-epic/epic.json

# 2. Vérifier les slides
ls -la parcours/epics/mon-epic/slides/

# 3. Rebuild le parcours
npm run build:parcours

# 4. Vérifier data/parcours.json
jq . data/parcours.json

Catalogue ne trouve pas un item#

Symptôme : Tool/game visible localement mais pas dans le catalogue

Solutions :

# 1. Rebuild le catalogue
npm run build:catalogue

# 2. Vérifier data/catalogue.json
jq . data/catalogue.json | grep "mon-item"

# 3. Vérifier le manifest
# tools/mon-tool/tool.json doit contenir :
# - id (unique)
# - title
# - description
# - type: "tool"

# 4. Vérifier le chemin
# Doit être tools/<id>/tool.json (pas tools/<id>/index.html)

Obtenir de l'aide#

Si votre problème persiste :

1. Chercher dans la documentation#

# Grep dans tous les docs
grep -r "votre-probleme" docs/

2. Chercher dans les issues GitHub#

Issues ouvertes : https://github.com/z4ppy/playlab42/issues
Issues fermées : peut contenir la solution

3. Ouvrir une issue#

Avant d'ouvrir :

Vérifier qu'elle n'existe pas déjà
Préparer les informations nécessaires

Template d'issue :

## Description
[Description claire du problème]

## Steps to reproduce
1.
2.
3.

## Comportement attendu
[Ce qui devrait se passer]

## Comportement observé
[Ce qui se passe réellement]

## Environnement
- OS: [macOS 13, Ubuntu 22.04, Windows 11, etc.]
- Docker version: [docker --version]
- Node version (dans container): [node --version]
- Navigateur: [Chrome 120, Firefox 121, etc.]

## Logs

[Coller les logs pertinents]


## Screenshots
[Si applicable]

4. Contacter les mainteneurs#

Mentionner @z4ppy dans une issue
Ouvrir une Discussion GitHub

Commandes de diagnostic#

Vérifier l'environnement complet#

#!/bin/bash
echo "=== Diagnostic Playlab42 ==="
echo ""

echo "1. Docker:"
docker --version
docker ps | grep playlab42

echo ""
echo "2. Node.js (dans container):"
make npm CMD="--version"

echo ""
echo "3. Dépendances:"
make npm CMD="list --depth=0"

echo ""
echo "4. Git:"
git status
git log --oneline -5

echo ""
echo "5. Build:"
ls -la data/*.json

echo ""
echo "6. Tests:"
make test 2>&1 | tail -10

echo ""
echo "=== Fin diagnostic ==="

Sauvegarder dans scripts/diagnose.sh et exécuter :

chmod +x scripts/diagnose.sh
./scripts/diagnose.sh > diagnostic.log 2>&1

Partager diagnostic.log lors de l'ouverture d'une issue.

Ressources#

Document maintenu par l'équipe Docaposte Dernière mise à jour : 2025-12-14