For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /fr/docs/tanstack/troubleshooting.md (or send Accept: text/markdown).
Dépannage
Diagnostiquez les problèmes de configuration à la frontière réellement en échec.
Configuration et paramètres
Avant toute étape, lisez Avant de commencer et Principes de base du terminal. Ces instructions supposent que vous avez ouvert le monorepo supastack complet dans VS Code ; sa racine package.json marque la racine du référentiel. Dans les commandes pnpm, un package d'espace de travail est une application ou un dossier de code partagé ; dans le produit, un espace de travail est le conteneur de données et la limite de sécurité d'une équipe. corepack pnpm --filter ... sélectionne un package dans le monorepo tandis que les commandes sont exécutées à partir de sa racine. Si vous avez ouvert uniquement un dossier mobile ou de bureau synchronisé, il ne contient pas le backend Web, la configuration Docker ou les scripts racine : exécutez le backend à partir de ce monorepo ou d'un serveur hébergé accessible et utilisez les propres scripts du dossier de plateforme. Une variable d'environnement est un paramètre nommé stocké dans un fichier .env local ou dans votre tableau de bord d'hébergement ; redémarrez l'application concernée après l'avoir modifiée et conservez les secrets du serveur en dehors des valeurs NEXT_PUBLIC_ et EXPO_PUBLIC_.
1. Copiez la première ligne d'erreur utile et la commande qui l'a produite ; ne collez pas de valeurs secrètes.
2. À partir de la racine du référentiel, exécutez le corepack pnpm --filter @supastack/web-tanstack typecheck pour les erreurs de type Web ou le corepack pnpm test pour la suite automatisée.
3. Pour un problème de navigateur, démarrez Web avec le corepack pnpm --filter @supastack/web-tanstack dev et reproduisez-le sur http://localhost:3000. Attendu : vous pouvez savoir si l'échec vient de la configuration, du code, de la base de données, du fournisseur ou du navigateur avant de modifier les paramètres.
Avant de modifier la configuration, lisez la commande en échec et la première erreur pertinente. Déterminez si le problème concerne l’installation des dépendances, la compilation, la validation de l’environnement, l’accès à la base, la distribution à un fournisseur ou le comportement du navigateur.
corepack pnpm --filter @supastack/web-tanstack typecheck
corepack pnpm --filter @supastack/web-tanstack build
corepack pnpm testCommandes à copier
Suivez les commentaires pour voir dans quel dossier une commande s'exécute. Si deux terminaux sont étiquetés, ouvrez deux fenêtres de terminal et laissez la première commande s'exécuter pendant que vous utilisez la seconde.
corepack pnpm --filter @supastack/web-tanstack typecheck
corepack pnpm testErreurs de premier lancement, décodées
Le premier lancement échoue d'un petit nombre de façons. Faites correspondre la première ligne d'erreur rouge à une ligne du tableau — les erreurs suivantes sont généralement des conséquences de la première, donc corrigez celle du haut avant tout le reste.
| Symptôme | Cause probable | Premier correctif |
|---|---|---|
| node, corepack ou pnpm n'est pas reconnu / commande introuvable | L'outil n'est pas installé, ou le terminal était ouvert avant la fin de l'installation | Installez-le (ou rouvrez le terminal), puis réessayez node --version |
| Aucun package.json trouvé / ENOENT package.json | Le terminal est dans le mauvais dossier | Faites cd jusqu'à la racine du dépôt — le dossier qui contient package.json — puis réessayez |
| EADDRINUSE / le port 3000 est déjà utilisé | Un autre serveur de dev occupe encore le port | Trouvez le terminal de ce serveur et appuyez sur Ctrl + C, puis relancez |
| ECONNREFUSED vers localhost:5432 ou une erreur de connexion à la base de données | Postgres n'est pas démarré | Exécutez docker compose up -d postgres, attendez l'état healthy, puis réessayez |
| Erreur de validation d'environnement nommant une clé manquante | `apps/web-tanstack/.env.local` est absent ou contient une valeur requise vide | Copiez la clé nommée depuis `.env.example`, donnez-lui une valeur, enregistrez et redémarrez le serveur |
| corepack ou pnpm introuvable après corepack enable | Aucun shim pnpm n'est sur le PATH | Utilisez corepack pnpm ... directement — il n'a jamais besoin de shim ; sous Windows utilisez corepack.cmd |
| PowerShell dit qu'un script .ps1 ne peut pas s'exécuter / est bloqué | La politique de scripts de PowerShell bloque le shim | Utilisez la forme .cmd — corepack.cmd pnpm install — aucun changement de politique nécessaire |
Processus d’implémentation
Si l’API est inaccessible, vérifiez que le serveur fonctionne et que l’origine configurée correspond à celle du client. Si aucun choix d’IA n’est disponible, examinez AI_MODEL_POLICY et les entrées activées du catalogue. Pour une tâche mise en file dont l’issue est incertaine, utilisez le parcours de reprise enregistré au lieu de soumettre une nouvelle tâche.
Pour les problèmes de mise en page du navigateur, examinez les styles calculés et reproduisez la taille exacte de la fenêtre. Les jetons du chrome produit se trouvent dans app-theme.css (palettes dans catalog.ts) ; le verrou de marque marketing est dans theme.css. La spécificité peut encore donner priorité aux styles de composants. Vérifiez le rayon rendu et pas uniquement la déclaration du jeton.
Vérification et dépannage
Si la page est sur :3001, ouvrez :3000 pour l'application Web ; :3001 appartient au serveur apps/docs distinct. Si un test demande un accès à la base de données, utilisez une base de données de développement isolée et vérifiez les deux emplacements .env. Si la même erreur persiste, incluez la commande et la première ligne d'erreur nettoyée lorsque vous demandez de l'aide ; ne désactivez jamais les contrôles d’accès et n’imprimez jamais de secrets dans les journaux.
Ne résolvez pas un contrôle en échec en désactivant l’autorisation, en journalisant des secrets ou en considérant que des contrôles d’infrastructure ignorés sont réussis. Préparez une reproduction minimale et la configuration pertinente sans secret. Après la correction, relancez le contrôle en échec puis les tests de régression concernés.