Comment déboguer les erreurs CORS dans le navigateur

Vous déclenchez une requête fetch, ouvrez la console et voyez quelque chose comme :

Access to fetch at ‘https://api.example.com’ from origin ‘http://localhost:3000’ has been blocked by CORS policy.

Avant de commencer à modifier les en-têtes du serveur au hasard, arrêtez-vous. La plupart du débogage CORS dans le navigateur se résume à lire ce que le navigateur vous dit déjà — si vous savez où chercher.

Ce que signifient réellement les erreurs CORS

Les erreurs CORS (Cross-Origin Resource Sharing) se produisent lorsque votre navigateur bloque une requête cross-origin parce que la réponse du serveur n’incluait pas les bonnes permissions. Le mot clé est navigateur — la requête atteint souvent le serveur. Le blocage se produit au retour.

Une origine est définie par la combinaison du protocole, du domaine et du port. Ainsi, http://localhost:3000 et http://localhost:4000 sont des origines différentes, même sur la même machine.

Comment déboguer les erreurs CORS avec les DevTools

Ouvrez DevTools → onglet Network (F12 ou Cmd+Option+I). Reproduisez la requête défaillante. Ensuite :

1. Trouvez la requête échouée — recherchez une entrée rouge ou filtrez par “Fetch/XHR”.
2. Vérifiez l’onglet Console — le message d’erreur y est spécifique. Il vous indique quel en-tête est manquant ou incorrect.
3. Cliquez sur la requête → onglet Headers — inspectez à la fois les en-têtes de requête (notamment Origin) et les en-têtes de réponse (notamment Access-Control-Allow-Origin).

L’erreur de console est votre principal outil de diagnostic. Les versions modernes de Chrome et Firefox donnent des messages précis comme :

• “No ‘Access-Control-Allow-Origin’ header is present” → le serveur n’a envoyé aucun en-tête CORS.
• “The value of ‘Access-Control-Allow-Origin’ must not be the wildcard ’*’ when credentials mode is ‘include’” → vous utilisez credentials: 'include' mais le serveur a répondu avec *.
• “Method PUT is not allowed by Access-Control-Allow-Methods” → le preflight a rejeté votre méthode HTTP.

Déboguer les requêtes preflight (OPTIONS)

Lorsque votre requête utilise une méthode non simple (PUT, DELETE, PATCH), des en-têtes personnalisés ou un type de contenu autre que les quelques-uns autorisés par la spécification, le navigateur envoie d’abord une requête preflight OPTIONS. Si celle-ci échoue, votre requête réelle n’est jamais envoyée.

Dans l’onglet Network, filtrez par “All” et recherchez une requête OPTIONS vers la même URL, apparaissant juste avant votre requête principale. Cliquez dessus et vérifiez :

• En-têtes de requête : Access-Control-Request-Method et Access-Control-Request-Headers — ceux-ci indiquent au serveur ce dont la vraie requête a besoin.
• En-têtes de réponse : Access-Control-Allow-Methods, Access-Control-Allow-Headers, Access-Control-Allow-Origin — le serveur doit explicitement autoriser chacun d’eux.

Si la requête OPTIONS retourne un code de statut 4xx ou 5xx, il s’agit probablement d’une erreur de routage ou de configuration côté serveur, et non d’une mauvaise configuration des en-têtes CORS. Corrigez d’abord l’erreur sous-jacente.

Est-ce vraiment une erreur CORS ?

Toutes les erreurs qui apparaissent comme CORS ne sont pas causées par CORS. Les faux positifs courants incluent :

• Contenu mixte — récupérer du http:// depuis une page https:// est bloqué par la politique de contenu mixte du navigateur, indépendamment des en-têtes CORS.
• Erreurs TLS/certificat — un échec de handshake TLS peut ressembler à un échec CORS dans la console.
• Redirections vers une origine différente — si le serveur redirige votre requête vers une nouvelle origine, le navigateur bloque la requête. Les redirections cross-origin ne sont pas autorisées pour les requêtes CORS.
• Extensions de navigateur — les extensions de confidentialité ou de blocage de publicités peuvent annuler les requêtes avant même que CORS ne soit évalué.
• Restrictions de cookies tiers — si vous utilisez credentials: 'include', les navigateurs modernes peuvent bloquer les cookies d’origines tierces même lorsque vos en-têtes CORS sont parfaitement corrects.

Pour isoler la vraie cause, essayez la requête dans une fenêtre privée/incognito avec les extensions désactivées.

Requêtes avec credentials : un piège courant

Si vous utilisez fetch(url, { credentials: 'include' }), le serveur ne peut pas répondre avec Access-Control-Allow-Origin: *. Il doit renvoyer l’origine exacte qui fait la requête. Le serveur doit également inclure Access-Control-Allow-Credentials: true dans sa réponse. Manquez l’un ou l’autre et le navigateur bloque la réponse.

Liste de vérification rapide pour le débogage CORS

Conclusion

Le message d’erreur du navigateur, l’onglet Network et le panneau Headers vous donnent tout ce dont vous avez besoin pour diagnostiquer la plupart des problèmes CORS en moins de cinq minutes. Lisez l’erreur exacte, trouvez la requête OPTIONS si elle existe, comparez ce qui a été envoyé avec ce qui était attendu, et travaillez à partir de là. Résistez à l’envie d’ajouter aveuglément Access-Control-Allow-Origin: * à votre serveur — comprenez d’abord ce que le navigateur demande, et répondez précisément.

FAQ

Gain control over your UX

See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay. — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.