Dépannage des builds
Corrigez les échecs de build courants en reliant messages d'erreur, causes et solutions : configuration, dépendances, syntaxe MDX et icônes.
Lorsqu'un build échoue, le journal de build indique ce qui a échoué et où. Trouvez votre message d'erreur ci-dessous et passez directement à la solution.
Consulter les détails de l'erreur
- Ouvrez l'onglet Deployments de votre projet
- Cliquez sur le build en échec
- Lisez le message d'erreur et faites défiler le journal de build
Le journal indique le fichier exact et la ligne qui ont arrêté le build.
Erreurs courantes
Erreurs de configuration
Invalid docs.json signifie que votre fichier de configuration ne peut pas être analysé. La cause est presque toujours mineure : une virgule en trop, un crochet non fermé, un guillemet manquant.
Recherchez les virgules, crochets ou guillemets manquants.
Exécutez jamdesk validate pour voir les erreurs exactes.
Corrigez-les et poussez pour déclencher un nouveau build.
Pages manquantes
Une erreur Page not found se déclenche lorsque votre navigation pointe vers un fichier qui n'existe pas. Vérifiez que le nom du fichier correspond au chemin dans docs.json, que la casse est exactement identique, et que vous avez omis l'extension .mdx.
Erreurs de syntaxe MDX
MDX compilation failed indique un MDX ou JSX malformé sur une page. Il s'agit généralement d'une balise non fermée (un <Card> sans </Card> correspondant), d'un caractère non échappé comme un { littéral là où vous vouliez \{, ou d'une syntaxe de prop invalide.
Dépassement du délai de build
Build exceeded time limit signifie exactement cela : le build a dépassé le temps imparti. Les images volumineuses et non optimisées en sont généralement la cause. Compressez-les, découpez les pages qui sont devenues trop grandes, et supprimez les pages que vous ne publiez plus.
Avertissements de build
Les avertissements n'entraînent jamais l'échec d'un build ; votre site est publié dans tous les cas. Ils signalent des problèmes à corriger et apparaissent à trois endroits : l'e-mail de build-warnings, l'entrée du build dans l'onglet Deployments, et votre terminal lorsque vous exécutez jamdesk validate ou jamdesk dev.
Images manquantes
Image not found avertit qu'une page référence une image absente de votre projet.
Jamdesk vérifie chaque référence d'image (Markdown  ainsi que src sur les balises <img loading="lazy"> et <Image>) par rapport aux fichiers de votre dépôt. Lorsque la cible est manquante, l'avertissement vous indique la page, le numéro de ligne et le chemin non résolu, afin qu'une image cassée ne soit jamais publiée silencieusement en 404.
Pour corriger cela, téléversez l'image ou redirigez le chemin vers un fichier existant. Les chemins sont sensibles à la casse et se résolvent soit depuis la racine de votre projet (avec un / en début), soit de manière relative à la page. Une référence à photo.png fonctionne toujours après que l'optimisation des images l'a convertie en WebP.
Les références aux URL externes, aux URI data:, et la syntaxe d'image affichée dans des blocs de code sont ignorées, de sorte que les exemples dans votre propre documentation ne déclenchent jamais de faux avertissement.
Étapes de débogage
Le journal indique le fichier exact et la ligne à l'origine de l'erreur. Commencez par là.
Exécutez jamdesk dev pour reproduire l'échec sur votre propre machine.
Exécutez jamdesk validate pour vérifier votre docs.json, puis jamdesk broken-links pour détecter les liens internes cassés.
Examinez votre dernier commit. Avez-vous ajouté une page ou modifié la configuration ?
Toujours bloqué ?
Si rien de ce qui précède ne résout le problème :
- Copiez l'intégralité du journal de build
- Notez l'ID de votre projet (il figure dans l'URL)
- Contacter le support