Une erreur 404 dans Express ne signale pas toujours une route manquante. Avant de toucher au code, nous recommandons de vérifier si la réponse 404 provient bien du processus Node ou d’une couche intermédiaire (reverse proxy, CDN, pare-feu applicatif). La confusion entre ces sources est la première cause de débogage inutile sur les projets Express en production.
Diagnostic d’une 404 Express : distinguer la vraie source de l’erreur
Le réflexe habituel consiste à ajouter un middleware catch-all en fin de pile et à considérer le problème réglé. Cette approche masque un défaut de diagnostic. Une requête peut retourner un code 404 sans jamais atteindre le processus Express.
A lire également : Que signifie l'expression « longue traîne » ?
Vérifier que la requête arrive bien à Express
La première étape consiste à loguer toutes les requêtes entrantes avec un middleware placé tout en haut de la pile, avant les routes. Si la requête n’apparaît pas dans les logs Express, la 404 est produite en amont du processus Node. Le problème se situe alors au niveau du reverse proxy (Nginx, Apache, Traefik) ou du CDN.
Nous utilisons un middleware minimal en tête de chaîne :
A lire également : Que fait l'IA SEO ?
app.use((req, res, next) => { console.log(req.method, req.originalUrl); next(); });
Si la ligne s’affiche, Express reçoit la requête. Sinon, le diagnostic se déplace vers la configuration du proxy ou du réseau.
Identifier une 404 générée par le proxy ou le CDN
Nginx renvoie sa propre page 404 quand la directive proxy_pass pointe vers un upstream injoignable ou quand une règle location ne transmet pas le chemin. Le corps HTML de la réponse contient alors la signature « nginx » ou « cloudflare », pas le contenu renvoyé par Express.
- Inspecter les en-têtes de réponse HTTP : un header
server: nginxouserver: cloudflaresur une 404 indique que la réponse ne vient pas d’Express - Comparer l’URL demandée avec les règles de routage du proxy : un
location /api/avec trailing slash ne transmet pas/apisans slash - Vérifier les règles du WAF (pare-feu applicatif) : certaines règles de sécurité bloquent des chemins ou des méthodes HTTP en renvoyant un code 404 plutôt qu’un 403, pour ne pas révéler l’existence de la ressource
- Contrôler la variable d’environnement
PORT: si Express écoute sur un port différent de celui configuré dans le proxy, toutes les requêtes tombent en 404 côté proxy
Ordre des middlewares Express et erreur 404 fantôme
L’ordre de déclaration des middlewares détermine le comportement de la 404. Un middleware catch-all placé avant une route valide intercepte la requête et renvoie une 404 alors que la route existe. Ce type de bug ne produit aucune erreur dans les logs, ce qui le rend difficile à repérer.
Express évalue les middlewares séquentiellement. Le middleware de gestion 404 doit se trouver après la dernière route déclarée, sans exception.
Le piège du chargement dynamique des routes
Sur les projets qui chargent les fichiers de routes via un glob ou un require dynamique, l’ordre d’import n’est pas garanti par le système de fichiers. Un fichier routes/users.js peut se charger après le middleware 404 si le tri alphabétique place le fichier catch-all avant.
Nous recommandons de déclarer explicitement le middleware 404 dans le fichier principal, après tous les appels app.use() des routeurs :
app.use('/api/users', usersRouter); app.use('/api/orders', ordersRouter); app.use((req, res) => { res.status(404).json({ error: 'Route introuvable' }); });
Cette séparation garantit que le handler 404 ne s’exécute que si aucune route n’a répondu.
404 sur une ressource existante : route trouvée, donnée absente
Les articles sur la gestion des erreurs 404 dans Express traitent presque exclusivement le cas de la route introuvable. En pratique, une part significative des 404 en production concerne une route valide qui ne trouve pas la ressource demandée (un identifiant inexistant en base, un fichier supprimé, un tenant désactivé).
La distinction a un impact direct sur le SEO et sur le comportement des clients API. Une 404 « route absente » et une 404 « ressource absente » ne se traitent pas de la même manière.
Séparer les deux types dans le code
Le middleware catch-all gère les routes non déclarées. Pour les ressources absentes, la réponse 404 doit partir du contrôleur, avec un corps explicite :
app.get('/api/users/:id', async (req, res, next) => { const user = await User.findById(req.params.id); if (!user) return res.status(404).json({ error: 'Utilisateur non trouvé', code: 'USER_NOT_FOUND' }); res.json(user); });
Le champ code permet au client de distinguer programmatiquement une erreur de routage d’une absence de donnée, sans parser le message texte.
Impact SEO des erreurs 404 Express sur les pages web
Google traite différemment une page qui renvoie un vrai code HTTP 404 et une page qui affiche un message d’erreur avec un code 200 (soft 404). Un soft 404 gaspille le budget de crawl et maintient des URL fantômes dans l’index.
Sur une application Express qui sert du contenu web (SSR ou pages statiques), le middleware 404 doit renvoyer explicitement res.status(404) et non un simple res.send('Page non trouvée') sans code de statut. Express envoie un code 200 par défaut si status() n’est pas appelé.
Vérification avec les outils Google
La Search Console signale les erreurs 404 dans le rapport de couverture. Pour une application Express, nous recommandons de croiser ce rapport avec les logs serveur pour identifier les URL crawlées qui génèrent des 404. Si une URL indexée devient 404, une redirection 301 vers la ressource de remplacement évite la perte de positionnement.
Le middleware 404 peut aussi renvoyer une page HTML utile pour l’utilisateur (liens vers les sections principales, champ de recherche) tout en conservant le code de réponse 404. Les deux objectifs, expérience utilisateur et signal SEO, ne sont pas contradictoires.
Sur les projets Express en production, la gestion de la 404 n’est pas un ajout de fin de projet. C’est un composant à part entière du routage, qui touche au diagnostic réseau, à la logique métier et au référencement. Traiter les trois dimensions dès la mise en place du serveur évite la majorité des tickets de support liés aux pages introuvables.
