Astro : dépannage

Procédure de diagnostic

node --version
npx astro --version
npx astro check            # types, composants, frontmatter
npx astro sync             # régénère les types des collections
rm -rf node_modules/.astro dist .astro
npm run build

Lire le premier message d’erreur : les suivants en découlent souvent. Le nom du fichier et la ligne sont indiqués.

Erreurs de compilation

Message	Cause et solution
`Cannot find module`	Dépendance absente (`npm install`), ou mauvais chemin relatif
`Expected "}" but found …`	Accolade ou balise non fermée dans le gabarit
`Unexpected token`	Syntaxe TypeScript dans un fichier `.js`
`getStaticPaths() function is required for dynamic routes`	Route `[param]` en mode statique
`Missing parameter`	`getStaticPaths` renvoie des paramètres incomplets
`InvalidContentEntryDataError` / `Invalid frontmatter`	Frontmatter non conforme au schéma de la collection
`Could not find requested image`	Chemin d’image incorrect
`ReferenceError: window is not defined`	Code navigateur exécuté côté serveur
`The collection … does not exist`	Collection non exportée dans `content.config.ts`

Types

npx astro check
npx astro sync

Les types astro:content sont générés : après l’ajout d’une collection, relancer astro sync (ou astro dev). Dans l’éditeur, installer l’extension officielle Astro pour la coloration et la vérification des fichiers .astro.

Interactivité

Symptôme	Piste
Composant inerte	Directive `client:*` absente
Erreur d’hydratation	HTML serveur et rendu client différents (date, `Math.random`, `window`)
Script exécuté une seule fois avec `ClientRouter`	Utiliser `astro:page-load`
Styles absents après une navigation	Feuille de style chargée seulement dans certaines pages

Style et Tailwind

Symptôme	Piste
Les classes Tailwind n’ont aucun effet	`@import "tailwindcss";` absent du CSS global, plugin Vite non déclaré (voir Tailwind : dépannage)
Un `<style>` ne touche pas un composant enfant	Portée locale : `:global()`
Flash de thème au chargement	Initialiser le thème par un `<script is:inline>` dans le `<head>`

Build et déploiement

Symptôme	Piste
Build lent	Beaucoup d’images : optimiser ou réduire les formats ; `NODE_OPTIONS=--max-old-space-size=4096` en cas de manque de mémoire
`JavaScript heap out of memory`	`NODE_OPTIONS=--max-old-space-size=4096 npm run build`
Site correct en `dev`, cassé en production	Chemins sensibles à la casse sous Linux (`Image.jpg` ≠ `image.jpg`), variables `PUBLIC_` absentes au build
404 qui renvoie 200	Configuration du serveur : voir Rendu et déploiement
Page `/chemin` redirigée vers `/chemin/`	`trailingSlash`

Mise à niveau

npx @astrojs/upgrade
npm outdated astro

Sauvegarder (commit) avant la montée de version.
Lire le guide de migration de la version visée (guide de mise à jour).
Mettre à jour Astro et les intégrations ensemble (@astrojs/upgrade).
npx astro check, npm run build, parcourir le site.

Changement notable d’Astro 7 : le traitement du Markdown est assuré par un processeur natif ; les options remarkPlugins / rehypePlugins demandent d’installer @astrojs/markdown-remark et de le configurer explicitement.

Obtenir de l’aide

Lire les messages du terminal jusqu’au bout (Astro propose souvent la correction).
Chercher le texte exact de l’erreur dans la documentation et les tickets du projet.
Réduire le problème à un exemple minimal avant de demander de l’aide.

Ubuntu 24.04 et 26.04 : différences à connaître

Aucune propre à Astro. Sous Linux, la casse des noms de fichiers compte, contrairement à certains systèmes de développement : vérifier les imports.

Pour aller plus loin

Résolution des problèmes
Retour : Installation et structure