Build Astro en échec ? Diagnostiquez ces 7 causes en 5 minutes

Le terminal affiche des lignes rouges partout. En local, tout va bien : npm run dev est rapide, les composants s’affichent parfaitement, les routes fonctionnent. Mais dès que vous lancez astro build, tout explose.

Un échec de build Astro compte parmi les problèmes les plus frustrants pour un développeur frontend. L’écart entre l’environnement local et le build de production laisse perplexe. Les messages d’erreur font souvent des dizaines de lignes, remplis de jargon technique — difficile de savoir par où commencer.

Récap de nos galères avec Astro : localiser un problème en 5 minutes (sans tâtonnements), 7 scénarios d’échec de build les plus courants et leurs solutions, pièges spécifiques selon la plateforme (Vercel / Cloudflare Pages / GitHub Pages), et des bonnes pratiques préventives. En pratique, 90 % des échecs de build relèvent de ces 7 causes.

Référence rapide : tableau des messages d’erreur

Voici un tableau de référence pour un diagnostic rapide :

I. Cadre de diagnostic rapide : localiser le problème en 5 minutes

3 points clés pour lire un message d’erreur

Beaucoup de monde panique dès qu’une erreur apparaît. Pourtant, la réponse est souvent déjà dans le message. Voici 3 points clés pour l’interpréter rapidement :

1. Identifier le type d’erreur

Regardez la première ligne ou les mots-clés :

• SyntaxError : problème de syntaxe
• ModuleNotFoundError ou Cannot find module : dépendance introuvable
• ValidationError : échec de validation (souvent frontmatter Content Collections)
• ENOENT : fichier ou répertoire introuvable
• is not defined (document / window) : accès à une API navigateur pendant le rendu serveur

Par exemple, si vous voyez SyntaxError: Unexpected token 'with', c’est presque certainement une version Node.js trop basse.

2. Localiser l’erreur

Cherchez ces informations plus bas :

at /path/to/your/file.astro:23:5

Cela indique le fichier et la ligne concernés (ici la ligne 23). Ne vous laissez pas distraire par les chemins node_modules — concentrez-vous sur le chemin de votre propre code.

Parfois l’erreur ne vient pas de votre code mais d’une dépendance. Dans ce cas, regardez le haut de la stack trace : vous trouverez souvent un indice du type Error: xxx caused by.

3. Comprendre le contexte

Notez à quelle étape l’erreur apparaît :

• Building for production... → erreur en phase de build
• Rendering... → erreur en phase de rendu de page
• vite v5.0.0 building for production... → erreur au niveau Vite

Les erreurs en phase de build sont généralement liées à la config ou aux dépendances ; celles en phase de rendu concernent plutôt la logique du code.

Méthode de diagnostic en 5 étapes

Maintenant que vous savez lire un message d’erreur, suivez ces 5 étapes — la plupart des problèmes se localisent ainsi :

Étape 1 : vérifier la version Node.js

node -v

Astro exige Node.js 18.17.1+ ou 20.3.0+. Si votre version est inférieure, mettez à jour. Beaucoup restent bloqués ici, car de nombreuses plateformes de déploiement utilisent encore une version Node ancienne par défaut.

Avec nvm, vous pouvez basculer ainsi :

nvm use 20

Étape 2 : vérifier l’installation des dépendances

npm list  # ou pnpm list

Cherchez des mentions UNMET DEPENDENCY ou missing — signe que des dépendances ne sont pas installées.

Comparez aussi les dates de modification de package.json et package-lock.json. Si le lock file est ancien, les dépendances peuvent être désynchronisées.

Étape 3 : nettoyer le cache et reconstruire

Simple et efficace. Face à une erreur bizarre, ma première réaction est de vider le cache :

# Supprimer build et dépendances
rm -rf node_modules .astro dist
# Réinstaller
npm install
# Retenter le build
npm run build

Au moins 30 % des problèmes se règlent ainsi. Cache corrompu ou versions de dépendances incohérentes : très courant.

Étape 4 : vérifier les fichiers modifiés récemment

Qu’avez-vous changé depuis le dernier build réussi ? Un nouveau composant ? Une config modifiée ? Une nouvelle dépendance ?

Consultez les changements récents :

git diff HEAD

Le problème vient souvent des un ou deux derniers commits. Commentez temporairement le code récent pour voir si le build passe — cela isole rapidement la cause.

Étape 5 : comparer l’environnement local et CI

Si le build passe en local mais échoue en CI/CD ou sur la plateforme de déploiement, c’est un problème d’environnement. Vérifiez :

• Version Node : identique en local et en production ?
• Gestionnaire de paquets : npm, pnpm ou yarn ? Même version ?
• Variables d’environnement : toutes configurées en production ?
• Versions des dépendances : le lock file est-il commité ? Les versions installées en ligne correspondent-elles au local ?

J’ai déjà eu le cas : Node 20 en local, Node 18 par défaut sur Vercel, et une API disponible seulement sous Node 20 — échec en production. Résolu en fixant la version Node dans les paramètres Vercel.

II. 7 causes les plus fréquentes d’échec de build

Cause 1 : version Node.js incompatible

Messages typiques :

SyntaxError: Unexpected token 'with'

ou

error: Cannot use import statement outside a module

Cause profonde :

Astro nécessite Node.js 18.17.1 ou supérieur (ou 20.3.0+). Beaucoup d’échecs de build viennent d’une version trop basse.

Deux situations fréquentes :

1. Node mis à jour en local, mais la plateforme de déploiement reste sur une ancienne version
2. En équipe, des versions Node différentes entre développeurs

Solutions :

En local :

Avec nvm, le changement est simple :

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

nvm install 20
nvm use 20

Configuration par plateforme :

Vercel :
Paramètres du projet → General → Node.js Version, choisir 20.x

Cloudflare Pages :
Créer un fichier .nvmrc à la racine :

20

Netlify :
Créer netlify.toml à la racine :

[build.environment]
  NODE_VERSION = "20"

Prévention :

Ajoutez dans package.json la version Node requise :

{
  "engines": {
    "node": ">=18.17.1"
  }
}

Ainsi, npm install avec une version trop basse affichera un avertissement.

Cause 2 : conflits de dépendances ou problème de lock file

Messages typiques :

Error: Cannot find module 'astro'
ERR_MODULE_NOT_FOUND

ou plus étrange :

X [ERROR] The build was canceled

Scénarios courants :

1. Compatibilité des gestionnaires de paquets

Après Astro 4.11.2, le support de Bun et pnpm a évolué ; certains projets n’installaient plus les dépendances. J’ai eu le cas en passant de 4.11.1 à 4.11.2 — pnpm plantait, corrigé ensuite par l’équipe Astro.

2. Lock file et node_modules désynchronisés

Vous modifiez package.json sans mettre à jour le lock file, ou inversement : vous récupérez le lock d’un collègue sans réinstaller les dépendances.

3. Packages tiers problématiques

Certains packages posent souvent problème sous Astro :

• astro-compress : beaucoup de retours d’échec de build
• @supercharge/strings : erreurs du type is not a function
• nodejs-mysql : préférez mysql2, meilleure compatibilité

Solutions :

La méthode classique en trois temps :

# 1. Supprimer dépendances et cache
rm -rf node_modules .astro dist package-lock.json
# ou avec pnpm :
rm -rf node_modules .astro dist pnpm-lock.yaml

# 2. Nettoyer le cache du gestionnaire
npm cache clean --force
# ou pnpm store prune

# 3. Réinstaller
npm install
# En CI, pour aligner lock et dépendances :
npm ci

Si ça ne suffit pas, vérifier la config :

Les utilisateurs pnpm peuvent ajuster .npmrc :

shamefully-hoist=true
public-hoist-pattern[]=*astro*

Diagnostic par minimalisation :

Si vous suspectez une dépendance :

1. Créez un projet Astro minimal :

npm create astro@latest minimal-test -- --template minimal

2. Ajoutez la dépendance suspecte et reproduisez l’erreur

3. Si reproduit, cherchez sur GitHub Issues des cas similaires

C’est ainsi que j’ai identifié astro-compress et opté pour une autre solution d’optimisation d’images.

Cause 3 : échec de validation Content Collections

Messages typiques :

Error: blog → post.md frontmatter does not match collection schema.
"date" must be a valid date

ou :

MarkdownContentSchemaValidationError: Content entry frontmatter does not match schema
"title" is required

Cause profonde :

Depuis Astro 2.0, Content Collections valide le frontmatter Markdown avec Zod. Puissant pour la sécurité des types, mais si le frontmatter est incorrect, le build échoue.

Au début, mes anciens articles avaient des frontmatters hétérogènes : dates en 2024-01-01 ou 2024/01/01, champs manquants. En activant Content Collections, tout a planté.

Erreurs fréquentes :

1. Champ obligatoire manquant

Le schema exige title, mais un fichier Markdown n’en a pas :

---
# title oublié
date: 2024-01-01
---

2. Type de champ incorrect

Souvent la date :

---
title: "My Post"
date: 2024/01/01  # devrait être 2024-01-01
---

Ou un tableau écrit comme une chaîne :

---
tags: javascript  # devrait être [javascript] ou ["javascript"]
---

3. Faute de frappe dans le nom de champ

Le schema définit description, vous écrivez desc — Astro rejette.

Solutions :

Étape 1 : vérifier la définition du schema

Ouvrez src/content/config.ts :

import { z, defineCollection } from 'astro:content';

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    date: z.date(),
    tags: z.array(z.string()).optional(),
  }),
});

export const collections = { blog };

Étape 2 : corriger le frontmatter selon le message d’erreur

Le message indique fichier et champ. Exemple :

blog → my-post.md frontmatter does not match collection schema.
"date" must be a valid date

Corrigez src/content/blog/my-post.md :

---
title: "Mon article"
date: 2024-01-01  # format YYYY-MM-DD
tags: ["astro", "blog"]
---

Étape 3 : .passthrough() pour les anciens articles

Beaucoup d’articles historiques à corriger un par un ? Assouplissez la validation :

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    date: z.coerce.date(),  // conversion automatique
    tags: z.array(z.string()).optional().default([]),
  }).passthrough(),  // champs extra autorisés
});

.passthrough() : les champs non définis dans le schema ne provoquent pas d’erreur.

Étape 4 : redémarrer le serveur de dev

Après modification du schema, redémarrez obligatoirement :

# Arrêter (Ctrl+C)
# Puis relancer
npm run dev

Ou, serveur en cours : s + Entrée pour resynchroniser la couche contenu.

Cause 4 : variables d’environnement mal configurées

Scénario typique :

npm run dev et npm run build OK en local, mais après déploiement sur Vercel / Cloudflare :

• page incomplète
• fonctionnalités cassées (commentaires, appels API)
• build OK mais erreur à l’exécution

Problèmes courants :

1. Variables absentes sur la plateforme

Vous avez un .env local, exclu par .gitignore (correct pour les secrets). La plateforme ne connaît pas ces valeurs — build ou runtime en échec.

2. Mauvaise utilisation du préfixe PUBLIC_

Règle Astro :

• variables accessibles côté client : préfixe PUBLIC_
• variables serveur : sans préfixe

Sans PUBLIC_, une variable utilisée côté client vaut undefined au build.

Exemple :

// .env
API_KEY=abc123
PUBLIC_SITE_URL=https://example.com

// Code client
const apiKey = import.meta.env.API_KEY;  // ❌ undefined
const siteUrl = import.meta.env.PUBLIC_SITE_URL;  // ✅ OK

Solutions :

Configuration par plateforme :

Vercel :

1. Projet → Settings → Environment Variables
2. Ajouter les variables (Production / Preview / Development)
3. Redéployer

Cloudflare Pages :

1. Projet → Settings → Environment variables
2. Production et Preview séparément
3. Relancer le build

Netlify :

1. Site settings → Environment variables
2. Ajouter les variables
3. Nouveau déploiement

Usage correct :

// astro.config.mjs
export default defineConfig({
  // Toutes les variables autorisées ici
  site: import.meta.env.PUBLIC_SITE_URL,
});

// src/pages/index.astro
---
// Code serveur : toutes les variables
const apiKey = import.meta.env.API_KEY;
const response = await fetch(`https://api.example.com?key=${apiKey}`);
---

<script>
  // Code client : uniquement PUBLIC_
  const siteUrl = import.meta.env.PUBLIC_SITE_URL;
  console.log(siteUrl);  // OK

  const apiKey = import.meta.env.API_KEY;
  console.log(apiKey);  // undefined
</script>

Sécurité :

Ne mettez jamais de secrets (clés API, mots de passe BDD) dans des variables PUBLIC_ — elles sont inlinées dans le JS bundle, visibles par tous.

Pour appeler une API depuis le client, passez par votre backend ; n’exposez pas la clé API directement.

Cause 5 : erreur de configuration

Messages typiques :

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

Parfois pas de message clair : build bloqué, boucle infinie, ou erreur Vite obscure.

Points sensibles :

1. base path incorrect (GitHub Pages)

L’URL GitHub Pages est https://username.github.io/repo-name/. Sans base dans astro.config.mjs, les ressources renvoient 404.

Mauvaise config :

export default defineConfig({
  site: 'https://username.github.io/my-blog/',
  // base oublié
});

Bonne config :

export default defineConfig({
  site: 'https://username.github.io',
  base: '/my-blog',  // nom du dépôt
});

2. Conflit d’intégrations

Des retours signalent un conflit entre l’intégration Svelte et content/config.ts, provoquant The build was canceled.

J’ai eu le cas avec plusieurs plugins d’optimisation d’images en conflit — en retirer un a suffi.

Solutions :

Vérifier base :

Pour un déploiement en sous-chemin (GitHub Pages) :

// astro.config.mjs
export default defineConfig({
  site: 'https://yourdomain.com',
  base: process.env.BASE_PATH || '/',  // / en local, chemin réel en prod
});

Puis en CI :

# .github/workflows/deploy.yml
env:
  BASE_PATH: /my-blog

Isoler un conflit d’intégrations :

Commentez les intégrations une par une :

// astro.config.mjs
export default defineConfig({
  integrations: [
    // react(),
    // tailwind(),
    // sitemap(),
  ],
});

Repartez du minimum, puis réactivez une par une pour trouver la coupable.

Cause 6 : package tiers incompatible SSG/SSR

Messages typiques :

ReferenceError: document is not defined
ReferenceError: window is not defined

Cause profonde :

Astro construit les pages côté serveur (Node.js). Certains packages npm ciblent le navigateur et accèdent à document, window, etc. À la construction, ces API n’existent pas — erreur.

Ma première fois : une librairie de graphiques. OK en dev (rendu navigateur), document is not defined au build.

Packages souvent concernés :

• Librairies UI manipulant le DOM
• Détection navigateur / appareil
• Anciens plugins jQuery
• Packages exécutant window.xxx au chargement du module

Solutions :

Option 1 : directive client:only

Indiquer à Astro de ne rendre le composant que côté client :

---
import ProblematicComponent from './ProblematicComponent';
---

<ProblematicComponent client:only="react" />

client:only exige le nom du framework (react / vue / svelte, etc.).

Option 2 : import dynamique

Charger le package uniquement côté client :

---
// Pas d'import côté serveur
---

<script>
  const { default: MyLibrary } = await import('problematic-package');
  const instance = new MyLibrary();
</script>

Option 3 : import conditionnel

let myLib;
if (typeof window !== 'undefined') {
  myLib = await import('problematic-package');
}

Option 4 : changer de package

Parfois le plus simple :

• nodejs-mysql → mysql2
• anciennes libs de graphiques → chart.js (compatible SSR)
• plugins jQuery → JS natif ou composants modernes

Conseil :

Avant d’ajouter une dépendance, vérifiez si la doc mentionne SSR/SSG. Beaucoup indiquent « works with Next.js » ou « SSR compatible » — en général compatible Astro aussi.

Cause 7 : breaking changes lors d’une montée de version Astro

Scénario typique :

Après passage à Astro 5 (ou autre version majeure), un projet qui buildait :

• build qui ne se termine jamais
• erreurs de résolution de modules
• APIs plus disponibles

Problèmes courants :

1. Résolution des modules CommonJS

Astro 5 a modifié la logique ; certains packages CommonJS ne passent plus.

2. APIs dépréciées ou modifiées

Chaque version majeure retire ou renomme des APIs (Astro.xxx, etc.).

3. Intégrations incompatibles

Après upgrade Astro, les intégrations officielles ou tierces doivent souvent suivre.

Stratégie :

Monter par paliers, pas d’un bond :

De Astro 3 à 5, ne sautez pas directement. Passez par 4, testez, puis 5.

# À éviter
npm install astro@latest

# Recommandé
npm install astro@^4.0.0
# après tests OK
npm install astro@^5.0.0

Outil de migration Astro :

npx @astrojs/upgrade

Il analyse le projet, suggère les mises à jour de dépendances et corrige certains appels d’API obsolètes.

Mettre à jour les intégrations :

npm install @astrojs/react@latest @astrojs/tailwind@latest @astrojs/sitemap@latest

Un échec de build vient parfois d’intégrations restées en version Astro 4 avec Astro 5.

III. Problèmes spécifiques par plateforme de déploiement

Au-delà des 7 causes générales, chaque plateforme a ses pièges.

Vercel

Problème 1 : timeout de build

La formule gratuite limite la durée de build. Gros projet ou installation lente → échec.

Solutions :

• Alléger package.json, retirer les dépendances inutiles
• Utiliser pnpm plutôt que npm (souvent plus rapide)
• Passer au plan Pro si le budget le permet

Problème 2 : mauvais répertoire de sortie

Vercel doit trouver les artefacts. Astro sort par défaut dans dist.

Config correcte :

• Build Command : npm run build ou astro build
• Output Directory : dist (défaut Astro)
• Install Command : npm install

Avec pnpm :

• Install Command : pnpm install

Cloudflare Pages

Problème 1 : version Node trop basse

Cloudflare Pages peut utiliser une version Node ancienne. Créez .nvmrc à la racine :

20

Ou dans les paramètres :
Settings → Environment variables → NODE_VERSION = 20

Problème 2 : astro-compress

🔥 Ne perdez plus des mois sur des produits sans demande ! Validez vos promesses SaaS avec Adsterra à petit budget →

Tester l'MVP →Pub

Beaucoup signalent des échecs de build sur Cloudflare avec astro-compress, surtout après optimisation d’images.

Si c’est votre cas :

1. Désinstaller : npm uninstall astro-compress
2. Retirer de astro.config.mjs
3. Utiliser <Image /> Astro ou une autre approche

Problème 3 : commande de build

• Build command : npm run build
• Build output directory : /dist
• Root directory : / (monorepo : ajuster)

Note : le répertoire de sortie commence souvent par /.

GitHub Pages

Problème 1 : 404 ou page blanche

Cause la plus fréquente : base mal configuré.

URL type : https://username.github.io/repo-name/ — /repo-name/ est le base path.

Dans astro.config.mjs :

export default defineConfig({
  site: 'https://username.github.io',
  base: '/your-repo-name',  // nom du dépôt
});

Problème 2 : styles ou ressources 404

Page visible mais sans CSS ou images : encore le base path.

Console navigateur : si la requête va vers https://username.github.io/style.css au lieu de https://username.github.io/repo-name/style.css, base manque.

IV. Bonnes pratiques préventives

Savoir corriger, c’est bien ; éviter de retomber dans le même piège, c’est mieux.

Workflow de diagnostic local

Reproduction minimale

Ne modifiez pas aveuglément le projet principal. Créez d’abord un cas minimal :

npm create astro@latest test-project -- --template minimal
cd test-project
# n'ajoutez que le code ou la dépendance suspecte

Si l’erreur se reproduit, c’est bien un composant ou une dépendance précise — diagnostic plus rapide.

Console navigateur et logs de build

En dev, gardez la console ouverte :

• Console : erreurs JavaScript
• Network : chargement des ressources
• Sources : débogage

Sauvegardez les logs de build :

npm run build > build.log 2>&1

Même si le terminal défile, vous gardez l’historique complet.

Carnet d’erreurs personnel

Je tiens un fichier Markdown : erreur, contexte, cause, solution, date.

## Erreur : SyntaxError: Unexpected token 'with'

**Contexte** : échec déploiement Vercel
**Cause** : version Node trop basse
**Solution** : Node 20.x dans les paramètres Vercel
**Date** : 2024-11-15

Au prochain cas similaire, 5 minutes suffisent parfois.

Santé du projet

Mettre à jour les dépendances

Chaque mois ou trimestre :

npm outdated
npm update
# ou une par une
npm install astro@latest

Ne montez pas les versions majeures sans lire le CHANGELOG.

Dependabot

.github/dependabot.yml :

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5

Dependabot ouvre des PR de mise à jour — il reste à review et merge.

Script de test de build

Dans package.json :

{
  "scripts": {
    "build": "astro build",
    "test:build": "npm run build && echo 'Build successful!'"
  }
}

Hook pre-commit

Avec husky, build avant chaque commit :

npm install --save-dev husky
npx husky init
echo "npm run build" > .husky/pre-commit

Plus lent à chaque commit, mais évite de pousser du code qui ne build pas.

Outils et ressources utiles

Officiel Astro :

1. Guide de dépannage
2. Référence des erreurs
3. Discord

Commandes utiles :

npx astro check
npx astro build --verbose
DEBUG=astro:* npm run dev

Communauté :

• Astro GitHub Issues
• Stack Overflow, tag [astro]
• Forums et blogs (retours d’expérience)

Conclusion

Récapitulons.

90 % des échecs de build Astro viennent de :

1. Node.js incompatible : ≥ 18.17.1 ou 20.3.0+
2. Dépendances : vider le cache, réinstaller, vérifier le lock file
3. Content Collections : corriger le frontmatter
4. Variables d’environnement : config plateforme, préfixe PUBLIC_
5. Fichiers de config : base path, conflits d’intégrations
6. Packages incompatible SSR : client:only ou import dynamique
7. Breaking changes de version : guide de migration, montée par paliers

Méthode en 5 étapes :

1. Version Node
2. Installation des dépendances
3. Cache + rebuild
4. Changements récents
5. Différences local / production

L’essentiel : une approche systématique. Lisez le message, identifiez type et emplacement, corrigez de façon ciblée.

Au début avec Astro, un échec de build pouvait me prendre des heures. Avec cette méthode, la plupart des cas se règlent en 5 à 10 minutes. J’espère que cet article vous fera gagner du temps.

Note : les versions évoluent vite. Cet article date de fin 2024 ; la stable était en 4.x. Si vous lisez ceci sous Astro 6 ou 7, croisez avec la doc officielle — APIs et messages peuvent changer, mais la logique de diagnostic reste valable.

Partagez vos nouveaux cas pour enrichir ce guide. Gardez-le sous la main : au prochain échec de build, consultez-le — gain de temps assuré.