_Assistant_Lead_Tech/90_debug_et_postmortem.md

Debug & post-mortems

Ce fichier sert à capitaliser sur les problèmes rencontrés.

À documenter

• bug pénible
• mauvaise compréhension
• fausse hypothèse
• solution finale

Objectif

Ne plus jamais perdre du temps sur le même problème.

---

Post‑mortems

SQL Server qui crash dans un conteneur LXC Proxmox

Contexte

NUC personnel sous Proxmox avec plusieurs services en conteneurs LXC. Un conteneur SQL Server (Microsoft SQL Server Linux) ne démarrait plus.

Symptômes

• sqlcmd impossible → timeout
• service mssql-server en boucle de restart
• logs contenant :

Operation not permitted
chmod: changing permissions of '/var/opt/mssql/log/...'

• crash + génération de core dump

Cause probable

SQL Server utilise certaines opérations système qui sont mal supportées dans les conteneurs LXC (permissions, filesystem, capabilities).

Dans un environnement Proxmox LXC, cela peut casser après :

• une mise à jour
• un changement de permissions
• un changement de configuration du conteneur

Conclusion

SQL Server n'est pas un bon candidat pour un conteneur LXC Proxmox.

Décision architecturale

Pour un homelab ou un petit serveur :

• éviter SQL Server en LXC
• préférer :
  • PostgreSQL
  • MariaDB / MySQL

Si SQL Server est nécessaire :

• utiliser une VM complète plutôt qu'un conteneur.

Règle à retenir

Éviter les bases lourdes nécessitant des capabilities système avancées dans des conteneurs LXC.

---

Suppression silencieuse due à deux éditions concurrentes sur le même fichier

Contexte

Un même fichier a été modifié par deux mécanismes proches dans le temps : édition en cours d’agent et passe outillée/linter/formatteur.

Symptômes

• bloc de code disparu sans erreur explicite
• diff final incohérent avec l’intention de modification
• impression de “régression fantôme” après une édition pourtant correcte

Cause probable

Deux processus ont réécrit le même fichier sans coordination, le second écrasant silencieusement une partie du travail du premier.

Correctif / règle à retenir

• éviter deux passes d’écriture concurrentes sur le même fichier
• relire le diff immédiatement après toute passe automatique
• privilégier une séquence stricte : édition, puis lint/format, puis vérification

---

tsx + NestJS : injection par type cassée silencieusement

Contexte

Projet app-alexandrie, Epic 3, le 10-03-2026. Le backend NestJS tournait avec tsx watch dans un contexte ESM (module: nodenext), notamment pour rester compatible avec Prisma v7.

Symptômes

• TypeError: Cannot read properties of undefined (reading 'get') dans le constructeur d’un service
• ConfigService injecté par type mais undefined au runtime
• @Injectable() et ConfigModule correctement configurés, sans erreur de compilation

Cause probable

tsx repose sur esbuild pour transpiler TypeScript. Dans ce contexte, emitDecoratorMetadata est ignoré même s’il est activé dans tsconfig.json. NestJS ne peut donc plus résoudre correctement certaines injections par type, notamment constructor(private readonly config: ConfigService).

Correctif / règle à retenir

• ne pas supposer que emitDecoratorMetadata fonctionne avec tsx
• dans ce contexte, éviter l’injection par type de ConfigService pour les services d’infra
• lire explicitement les variables via process.env, après chargement amont de ConfigModule.forRoot()

Exemple :

// AVANT
constructor(private readonly config: ConfigService) {
  const host = this.config.get('REDIS_HOST');
}

// APRES
constructor() {
  const host = process.env['REDIS_HOST'] ?? 'localhost';
}

Alternative écartée

nest start --watch a été testé mais a introduit des conflits ESM/CJS dans ce contexte (exports is not defined).

---

export { fn } ne constitue pas un import local — détecté uniquement au build

Contexte

Projet app-template-resto, story 2-4, le 17-03-2026. Dans getPublicHomeData.ts, la fonction resolvePublicTenantSelection avait été déplacée dans src/server/tenant/resolvePublicTenant.ts et re-exportée depuis l'ancien emplacement.

Symptômes

• Cannot find name 'resolvePublicTenantSelection' au next build uniquement
• ESLint et tsc (hors build) ne signalaient rien
• La fonction était utilisée localement dans le même fichier qui la re-exportait

Cause

// getPublicHomeData.ts
export { resolvePublicTenantSelection } from "@/server/tenant/resolvePublicTenant";

// puis, plus bas dans le même fichier :
const result = resolvePublicTenantSelection(env); // ← NameError au build

Un re-export (export { fn } from "...") ne crée pas de binding local dans le fichier. La fonction est exportée vers l'extérieur mais n'est pas disponible comme variable locale.

Correctif / règle à retenir

Si une fonction est utilisée dans le même fichier qui la re-exporte, ajouter un import séparé en plus du export :

import { resolvePublicTenantSelection } from "@/server/tenant/resolvePublicTenant";
export { resolvePublicTenantSelection }; // pour les appelants externes

---

CLI npm globale qui ne se met pas à jour (prefix / permissions / contexte projet)

Contexte

Mise à jour de @openai/codex via la CLI (codex update), sur une machine avec installation npm globale utilisateur (~/.npm-global) et exécution depuis un repo contenant un .npmrc non standard.

Symptômes

• Message d’update CLI affiché mais version inchangée après npm install -g
• codex --version reste sur une ancienne version
• Installation via sudo ne change rien
• which codex et npm root -g pointent vers des chemins différents

Cause

• Décalage entre :
  • le prefix npm utilisé pour installer
  • le binaire exécuté
• Ancienne installation toujours active dans le bon prefix utilisateur
• Contexte projet (.npmrc) pouvant influencer le comportement de npm

Correctif / règle à retenir

• Ne jamais utiliser sudo npm install -g
• S’assurer que :
  • npm config get prefix = dossier utilisateur (ex : ~/.npm-global)
  • which <cli> pointe vers ce même prefix
• Faire les installs globales hors d’un repo (éviter .npmrc projet)
• En cas de doute, nettoyer :

rm -rf ~/.npm-global/lib/node_modules/<package>
rm -f ~/.npm-global/bin/<cli>
npm install -g <package>@latest

Commandes de diagnostic utiles

• npm config get prefix
• which <cli>
• npm root -g
• npm ls -g --depth=0 <package> | npm list -g @openai/codex --depth=0
• --version