Aller au contenu principal

FAQ Troubleshooting — MyTV v2 API

Guide rapide pour résoudre les problèmes les plus fréquents.

Installation & Setup​

Q: npm install échoue avec des erreurs de permission​

Solution :

# Linux/macOS
sudo chown -R $USER:$USER ~/.npm

# Windows (PowerShell admin)
npm cache clean --force
npm install

Q: prisma:generate échoue avec "schema.prisma not found"​

Solution :

# Vérifier que le fichier existe
ls prisma/schema.prisma

# Si manquant, vérifier la branche git
git status
git checkout develop

Q: Port 3000 déjà utilisé​

Solution :

# Linux/macOS
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

# Ou utiliser un autre port
PORT=3001 npm run start:dev

Docker​

Q: docker-compose up échoue avec "network not found"​

Solution :

docker-compose down
docker network prune
docker-compose up -d

Q: Les conteneurs redémarrent en boucle​

Solution :

# Voir les logs
docker-compose logs api --tail=100

# Vérifier les ressources
docker stats

# Reconstruire les images
docker-compose build --no-cache
docker-compose up -d

Q: Impossible de se connecter à PostgreSQL depuis l'API​

Solution :

# 1. Vérifier que postgres est démarré
docker-compose ps postgres

# 2. Vérifier le réseau
docker network inspect mytelevision-network

# 3. Tester la connexion manuellement
docker exec -it mytv-postgres psql -U mytv -d mytv

# 4. Vérifier DATABASE_URL
# Doit être: postgresql://mytv:mytv_password@postgres:5432/mytv
# (postgres, pas localhost, dans Docker)

Base de données​

Q: "Prisma Migrate could not create the shadow database"​

Solution :

# L'utilisateur DB doit avoir les droits CREATEDB
# En dev, utiliser le superuser ou:
ALTER USER mytv CREATEDB;

# Ou désactiver la shadow database (non recommandé)
# Dans schema.prisma:
# shadowDatabaseUrl = env("SHADOW_DATABASE_URL")

Q: Migration bloquée ou corrompue​

Solution :

# 1. Voir le statut
npx prisma migrate status

# 2. Si "has failed", résoudre manuellement
npx prisma migrate resolve --rolled-back "nom_migration"

# 3. Réappliquer
npx prisma migrate dev

# 4. En dernier recours (PERD LES DONNÉES)
npx prisma migrate reset

Q: Erreur "P2002: Unique constraint failed"​

Cause : Tentative d'insérer une valeur dupliquée sur un champ unique.

Solution :

// Option 1: Utiliser upsert
await prisma.user.upsert({
  where: { email: '[email protected]' },
  update: { name: 'Updated Name' },
  create: { email: '[email protected]', name: 'New User' },
});

// Option 2: Vérifier avant d'insérer
const existing = await prisma.user.findUnique({
  where: { email: '[email protected]' },
});
if (existing) {
  throw new ConflictException('Email already exists');
}

Q: Problèmes de migration Prisma​

Diagnostic :

# Voir le status
npm run prisma:migrate status

# Voir les migrations
ls -la prisma/migrations/

Solutions :

# Reset (attention: perte de données)
npm run prisma:migrate:reset

# Force deploy
npx prisma migrate deploy

Authentification​

Q: "jwt expired" même avec un token fraîchement généré​

Causes possibles :

  1. Horloge système désynchronisée
  2. JWT_EXPIRATION trop court

Solution :

# Vérifier l'heure système
date

# Synchroniser l'horloge (Linux)
sudo ntpdate pool.ntp.org

# Vérifier JWT_EXPIRATION
echo $JWT_EXPIRATION  # Doit être "15m", "1h", "7d", etc.

Q: "Invalid signature" sur le JWT​

Causes possibles :

  1. JWT_SECRET différent entre génération et validation
  2. Token modifié ou corrompu

Solution :

# Vérifier que JWT_SECRET est identique partout
node -e "console.log(process.env.JWT_SECRET?.substring(0, 10) + '...')"

# Décoder le token (sans vérification)
# Install: npm install -g jwt-cli
jwt decode <TOKEN>

Q: Firebase Social Auth échoue avec "invalid token"​

Solution :

# 1. Vérifier la configuration Firebase
node -e "console.log('FIREBASE_PROJECT_ID:', process.env.FIREBASE_PROJECT_ID)"

# 2. Vérifier que la clé privée est correcte
node -e "console.log('Key starts with:', process.env.FIREBASE_PRIVATE_KEY?.substring(0, 30))"
# Doit commencer par: -----BEGIN PRIVATE KEY-----

# 3. Tester avec Firebase Admin SDK
# Dans un script de test
const admin = require('firebase-admin');
admin.initializeApp({...});
admin.auth().verifyIdToken(token);

Q: Token expiré (401)​

Solution :

# Utiliser le refresh token
curl -X POST http://localhost:3000/api/v2/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "eyJhbG..."}'

Cache & Performance​

Q: Les données ne se mettent pas à jour (cache stale)​

Solution :

# Vider le cache Redis
redis-cli -a $REDIS_PASSWORD FLUSHDB

# Ou cibler une clé spécifique
redis-cli -a $REDIS_PASSWORD DEL "cache:movies:*"

Q: L'API est lente (>500ms)​

Diagnostic :

# 1. Activer les logs de requêtes Prisma
DEBUG=prisma:query npm run start:dev

# 2. Identifier les requêtes N+1
# Chercher les patterns répétitifs dans les logs

# 3. Ajouter des includes dans les requêtes
const movies = await prisma.movie.findMany({
  include: { genres: true, cast: true },
});

Q: Erreur "429 Too Many Requests"​

Solution :

# En développement, relaxer les limites
THROTTLE_LONG_LIMIT=1000

# Ou vider les compteurs Redis
redis-cli -a $REDIS_PASSWORD KEYS "throttle:*" | xargs redis-cli DEL

Q: Rate Limit atteint (429) - Diagnostic avancé​

Diagnostic :

# Vérifier les headers
curl -I http://localhost:3000/api/v2/movies
# X-RateLimit-Limit
# X-RateLimit-Remaining
# X-RateLimit-Reset

Solutions :

  1. Attendre le reset (voir timestamp dans header)
  2. Réduire la fréquence des requêtes
  3. En dev - Augmenter les limites dans la config

API Endpoints​

Q: 404 sur un endpoint qui devrait exister​

Checklist :

# 1. Vérifier le préfixe API
# Les routes sont sous /api/v2/...
curl http://localhost:3000/api/v2/movies

# 2. Vérifier que le module est chargé
# Dans app.module.ts, le module doit être importé

# 3. Vérifier le routing
# Le controller doit avoir @Controller('movies')

Q: 400 Bad Request sur une requête valide​

Solution :

# 1. Vérifier le Content-Type
curl -H "Content-Type: application/json" ...

# 2. Vérifier le format JSON
echo '{"key": "value"}' | jq .  # Doit parser sans erreur

# 3. Voir les erreurs de validation détaillées
# Les erreurs sont retournées dans la réponse

Q: 500 Internal Server Error sans détails​

Solution :

# 1. Voir les logs complets
docker-compose logs api --tail=200

# 2. Activer le mode debug
LOG_LEVEL=debug npm run start:dev

# 3. Chercher l'erreur dans les logs
# L'erreur originale devrait être loguée

API ne démarre pas​

Symptôme​

Erreur au démarrage de l'API.

Diagnostic​

# Vérifier les logs
npm run start:dev 2>&1 | head -50

# Vérifier les variables d'environnement
cat .env | grep -v "^#" | grep -v "^$"

# Vérifier les services Docker
docker ps

Causes fréquentes​

  1. Variable d'environnement manquante

    cp .env.example .env
    # Compléter les valeurs manquantes

  2. PostgreSQL non accessible

    docker-compose up -d postgres
    docker logs mytv-postgres

  3. Port déjà utilisé

    lsof -i :3000
    kill -9 <PID>

  4. Prisma client non généré

    npm run prisma:generate

Erreur "STREAMING_SIGNING_SECRET is required"​

Solution​

# Ajouter dans .env (minimum 32 caractères)
echo "STREAMING_SIGNING_SECRET=$(openssl rand -base64 32)" >> .env

Erreur de connexion PostgreSQL​

Diagnostic​

# Vérifier le container
docker ps | grep postgres

# Tester la connexion
docker exec -it mytv-postgres psql -U mytv -d mytv_dev -c "SELECT 1"

# Voir les logs
docker logs mytv-postgres

Solutions​

# Redémarrer le container
docker-compose restart postgres

# Réinitialiser (attention: perte de données)
docker-compose down -v
docker-compose up -d postgres
npm run prisma:migrate:dev

Erreur Redis​

Diagnostic​

# Vérifier le container
docker ps | grep redis

# Tester la connexion
docker exec -it mytv-redis redis-cli ping

Solutions​

# Redémarrer Redis
docker-compose restart redis

# Vérifier le mot de passe
docker exec -it mytv-redis redis-cli -a $REDIS_PASSWORD ping

Tests​

Q: Les tests échouent avec "Cannot find module"​

Solution :

# Régénérer le client Prisma
npm run prisma:generate

# Vérifier la config Jest
cat jest.config.js | grep moduleNameMapper

Q: Tests E2E échouent par timeout​

Solution :

# Augmenter le timeout
npm run test:e2e -- --testTimeout=30000

# Ou dans le test
jest.setTimeout(30000);

Q: Tests de base de données polluent les données​

Solution :

// Utiliser des transactions pour rollback
beforeEach(async () => {
  await prisma.$executeRaw`BEGIN`;
});

afterEach(async () => {
  await prisma.$executeRaw`ROLLBACK`;
});

Q: Tests qui échouent - Diagnostic général​

Diagnostic :

# Voir les détails
npm run test -- --verbose

# Lancer un test spécifique
npm run test -- --testPathPattern="movies"

# Voir la couverture
npm run test:cov

Solutions :

  1. Mocks manquants - Vérifier les providers dans TestingModule
  2. Database non disponible - S'assurer que les services sont démarrés pour E2E
  3. Environment incorrect - Vérifier NODE_ENV=test

Build qui échoue​

Diagnostic​

npm run build 2>&1 | head -100

Solutions​

  1. Erreurs TypeScript

    npx tsc --noEmit

  2. Dépendances manquantes

    rm -rf node_modules package-lock.json
    npm install

Kubernetes / Production​

Q: Pod en CrashLoopBackOff​

Solution :

# 1. Voir les logs
kubectl logs -n mytv <pod-name> --previous

# 2. Vérifier les probes
kubectl describe pod -n mytv <pod-name>

# 3. Vérifier les ConfigMaps/Secrets
kubectl get configmap -n mytv
kubectl get secret -n mytv

Q: Service non accessible depuis l'extérieur​

Solution :

# 1. Vérifier l'Ingress
kubectl get ingress -n mytv
kubectl describe ingress -n mytv mytv-api

# 2. Vérifier le Service
kubectl get svc -n mytv

# 3. Tester depuis un pod
kubectl run -it --rm debug --image=busybox -- wget -qO- http://mytv-api/health

Commandes utiles​

# Redémarrer tout proprement
docker-compose down && docker-compose up -d

# Voir les logs en temps réel
docker-compose logs -f api

# Ouvrir Prisma Studio
npm run prisma:studio

# Vérifier la santé de l'API
curl http://localhost:3000/health

# Générer un secret sécurisé
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Lint et fix automatique
npm run lint

# Tests avec couverture
npm run test:cov