Comment lire une trace de pile et corriger l'erreur

Lorsque vous collez une trace de pile dans une barre de recherche et que vous pensez « expliquez-moi cette trace d'erreur », vous posez en réalité deux questions : qu'est-ce qui a cassé et quelle ligne de mon code en est la cause. Une trace de pile répond aux deux, mais seulement si vous la lisez dans le bon ordre. Ce guide enseigne la compétence générale de décoder n'importe quelle trace, en Python ou JavaScript, pour que vous arrêtiez de deviner et commenciez à réparer.

La plupart des tutoriels répondent à une erreur spécifique et vous laissent sans solution pour la suivante. La compétence qui se transfère réellement est la lecture de la trace elle-même : savoir où se trouve la vraie cause, quelles trames ignorer et comment transformer quarante lignes de jargon en un diagnostic d'une phrase. Cette compétence fonctionne pour toutes les erreurs que vous rencontrerez.

Ce qu'est réellement une trace de pile#

Une trace de pile est un instantané de la pile d'appels au moment exact où votre programme a planté. Elle liste chaque fonction en cours d'exécution, dans l'ordre où elles ont été appelées, ainsi que le type d'erreur et le message au point de défaillance. Lisez-la correctement et elle pointe directement vers la ligne défaillante.

Considérez-la comme une chaîne de « qui a appelé qui ». Votre programme entre dans main, qui appelle processOrder, qui appelle chargeCard, qui lève une exception. La trace enregistre toute cette chaîne pour que vous puissiez remonter du symptôme à la cause.

Deux éléments sont les plus importants :

• Le type d'exception et le message : quel type de défaillance s'est produit (une TypeError, une KeyError, une référence nulle) et une courte description en langage humain.
• Les frames : la liste ordonnée des appels de fonction, chacun avec un nom de fichier et un numéro de ligne.

Astuce rapide : le message d'erreur vous dit ce qui a mal tourné. Les frames vous disent où. Vous avez presque toujours besoin des deux pour corriger le problème, et ceux qui restent bloqués ne lisent généralement qu'un seul des deux.

Comment lire une stack trace de haut en bas#

Voici ce qui piège beaucoup de monde : Python et JavaScript affichent leurs traces dans des ordres opposés. Comprenez le bon sens et tout le reste devient clair.

Python : lisez de bas en haut#

En Python, la trace affiche l'appel le plus ancien en premier, le plus récent en dernier. L'en-tête indique Traceback (most recent call last), ce qui donne la marche à suivre. L'exception proprement dite se trouve sur la dernière ligne, et la ligne de code qui l'a déclenchée se situe juste au-dessus.

Traceback (most recent call last):
  File "app.py", line 42, in <module>
    main()
  File "app.py", line 30, in main
    total = calculate_total(cart)
  File "app.py", line 18, in calculate_total
    return sum(item["price"] for item in cart)
KeyError: 'price'

Commencez par le bas. KeyError: 'price' signifie qu'un dictionnaire ne contenait pas de clé price. La ligne juste au-dessus montre exactement où : ligne 18, dans calculate_total, dans cette expression génératrice. Tout ce qui se trouve au-dessus de la ligne 18 n'est que le chemin parcouru par le programme. Vous corrigez la ligne 18 (ou les données qui l'alimentent), pas main.

JavaScript : lisez de haut en bas#

JavaScript inverse l'ordre. Le message d'erreur se trouve sur la première ligne, et le cadre le plus haut est celui où l'erreur a été levée. Vous lisez vers le bas uniquement jusqu'à atteindre votre propre code.

TypeError: Cannot read properties of undefined (reading 'name')
    at renderUser (app.js:24:18)
    at renderList (app.js:51:9)
    at App (app.js:78:5)
    at react-dom.production.min.js:118:188

La première ligne est le diagnostic : quelque chose a tenté de lire .name sur une valeur undefined. Le premier cadre, renderUser à la ligne 24, est l'endroit où cela s'est produit. Les cadres en dessous sont les appelants. Le cadre du bas se trouve ici dans react-dom, du code de bibliothèque que vous n'avez pas écrit, donc vous l'ignorez.

Trouver la ligne qui a vraiment cassé#

L'habitude la plus utile est celle-ci : parcourez les frames et trouvez la première qui pointe vers votre fichier, pas une bibliothèque ou le runtime. Cette frame est presque toujours celle où vous devez regarder en premier.

Une trace réelle est un sandwich. Le haut (JS) ou le bas (Python) est l'exception brute. Le milieu est un mélange de votre code et du code du framework. L'astuce est de filtrer :

• Ignorez les frames du framework sauf si chaque frame est du code du framework (alors vous appelez probablement une API de manière incorrecte).
• Trouvez votre première frame : la frame JS la plus haute ou la frame Python la plus basse avec le chemin de votre propre fichier et le numéro de ligne.
• Ouvrez cette ligne et lisez le message d'erreur par rapport à ce que fait la ligne.

Faites correspondre le message à la ligne. KeyError: 'price' à côté de item["price"] signifie que la clé est manquante. Cannot read properties of undefined (reading 'name') à côté de user.name signifie que user est indéfini. Le message nomme l'opération cassée ; la ligne montre où vous l'avez écrite.

Lire le message d'erreur lui-même#

Le message est une phrase compressée. Décodez les plus courants et vous aurez décodé la plupart des plantages que vous rencontrerez.

Fragment de message d'erreur	Ce que cela signifie	Première chose à vérifier
Cannot read properties of undefined (reading 'x')	Vous avez accédé à .x sur quelque chose qui était undefined	Pourquoi l'objet est-il vide ou pas encore chargé
KeyError: 'x' (Python)	Un dictionnaire n'a pas de clé 'x'	Orthographe, ou si la clé existe toujours
TypeError: 'NoneType' object is not subscriptable	Vous avez indexé dans None	Qu'est-ce qui a retourné None au lieu d'une liste/dictionnaire
IndexError: list index out of range	Vous avez demandé un élément au-delà de la fin d'une liste	Limites de boucle, ou une liste vide
is not a function (JS)	Vous avez appelé quelque chose qui n'est pas appelable	Une faute de frappe, ou une valeur qui n'est pas ce que vous pensez
Maximum call stack size exceeded	Récursion infinie	Une fonction qui s'appelle elle-même sans cas de base

Un flux de débogage reproductible#

Une fois que vous savez lire une trace, intégrez-la dans une routine pour faire systématiquement les mêmes cinq choses au lieu de paniquer. Ce flux fait la différence entre une correction de cinq minutes et une heure de tâtonnements.

1. Lisez d'abord le type d'exception et le message. Nommez l'échec en termes simples avant de toucher à quoi que ce soit.
2. Trouvez votre premier cadre. En bas en Python, en haut en JavaScript. Ce fichier et ce numéro de ligne sont le point zéro.
3. Ouvrez cette ligne et formulez une hypothèse. "Cette variable est indéfinie ici car le fetch n'a pas été résolu." Une phrase.
4. Vérifiez avec une valeur, pas une supposition. Affichez ou loggez la variable suspecte juste avant la ligne qui échoue. Confirmez qu'elle correspond à ce que le message indique.
5. Corrigez la cause, pas le symptôme. Un garde-null masque le plantage, mais demandez-vous pourquoi la valeur était nulle. La vraie correction se trouve généralement un cadre plus haut.

Ce dernier point est là où la plupart des gens se trompent. Envelopper une ligne dans un try/except ou un chaînage optionnel ?. arrête le plantage sans rien corriger. La trace vous a donné un indice gratuit : la valeur était erronée en amont. Suivez-la.

Attention : ne "corrigez" jamais une trace en supprimant la ligne qu'elle pointe ou en captant silencieusement toutes les exceptions. Vous ne supprimez pas le bug, vous vous bandez les yeux pour le prochain.

Quand les traces pointent uniquement vers le code de la bibliothèque#

Parfois, chaque frame se trouve dans un framework ou une dépendance et aucune ne pointe vers votre fichier. C'est déroutant, mais cela a une signification claire : vous avez fourni une mauvaise entrée à la bibliothèque ou vous l'avez appelée de la mauvaise manière. La bibliothèque a planté à votre place.

Dans ce cas, regardez la frame la plus profonde qui touche la frontière entre votre code et le leur. Un pilote de base de données qui plante sur une requête mal formée, un analyseur JSON qui plante sur une chaîne cassée, un routeur qui plante sur une définition de route incorrecte. La correction se trouve dans la valeur ou l'appel que vous avez passé, même si l'explosion visible se produit dans leur code.

Le code asynchrone ajoute une autre complication. Les promesses, les callbacks et les threads peuvent produire des traces qui « sautent » car l'échec apparaît loin de l'endroit où l'appel original a été effectué. Les runtimes modernes ajoutent des frames asynchrones pour aider, mais si une trace semble incroyablement courte ou déconnectée, l'origine réelle peut être une promesse non attendue ou une erreur avalée ailleurs.

Laissez un décodeur de code l'expliquer pour vous#

Lire les traces est une compétence, et comme toute compétence, elle est lente avant de devenir rapide. Quand vous êtes face à une erreur inconnue dans un langage que vous utilisez rarement, coller l'intégralité dans un outil qui l'explique en français simple vous fait gagner du temps. Notre décodeur de code gratuit prend une trace brute et renvoie le type d'erreur, la cause probable et la ligne à vérifier, en modes débutant à expert.

L'honnête mise en garde : une explication par IA est une hypothèse forte, pas un verdict. Elle peut mal interpréter une pile inhabituelle ou inventer une cause qui semble plausible. Traitez sa réponse comme vous le feriez avec un collègue senior jetant un coup d'œil à votre écran, une indication rapide dans la bonne direction que vous confirmez ensuite en vérifiant la ligne et la valeur réelles.

Deux habitudes de vérification rapide vous protègent :

• Vérifiez le numéro de ligne. Si l'outil dit que le bug est à la ligne 18, ouvrez la ligne 18 et confirmez que le message correspond à ce que fait ce code.
• Méfiez-vous des API inventées. Si une correction suggérée fait référence à une méthode ou un package que vous ne reconnaissez pas, cherchez-le avant de lui faire confiance. Les noms de fonctions hallucinés sont la façon la plus courante dont ces outils induisent en erreur.

Pour les erreurs qui sont vraiment des problèmes de motif, comme une regex qui lève une exception ou ne correspond pas, associez l'explication à un testeur de regex en direct pour déboguer votre motif afin de voir exactement quels caractères correspondent. Et si l'explicateur vous donne une charge utile JSON confuse enfouie dans l'erreur, passez-la dans le formateur JSON pour rendre la structure lisible avant de continuer à lire la trace.

Mettre le tout ensemble#

La prochaine fois que vous devez expliquer cette trace de pile d'erreur, vous avez un processus au lieu d'une panique. Nommez l'exception, lisez dans la bonne direction (de bas en haut pour Python, de haut en bas pour JavaScript), trouvez le premier cadre dans votre propre code, et confirmez votre hypothèse avec une valeur réelle avant de changer quoi que ce soit. La trace n'est pas du bruit. C'est une carte avec la destination déjà marquée.

Lire les traces couramment est ce qui distingue les développeurs qui corrigent des bugs en quelques minutes de ceux qui perdent des après-midis. Construisez l'habitude sur de petites erreurs maintenant, et les traces effrayantes de quarante lignes cesseront d'être effrayantes.

Foire aux questions#

Est-ce que je lis une trace de pile du haut vers le bas ou du bas vers le haut ? Cela dépend du langage. Python affiche l'appel le plus ancien en premier et l'exception en dernier, donc on lit de bas en haut et la ligne qui échoue se trouve juste au-dessus du message d'erreur final. JavaScript place le message d'erreur et le cadre qui a levé l'exception en haut, donc on lit de haut en bas. Dans les deux cas, on cherche le premier cadre qui pointe vers votre propre code.

Que signifie réellement « Cannot read properties of undefined » ? Cela signifie que votre code a tenté d'accéder à une propriété ou une méthode sur une valeur qui était undefined. Par exemple, user.name alors que user n'a jamais été assigné. La correction ne se trouve rarement sur cette ligne elle-même ; il s'agit de comprendre pourquoi la valeur était vide, souvent à cause d'un chargement de données qui n'est pas terminé ou d'un objet qui n'a jamais été retourné.

Quelle ligne dans la trace dois-je corriger ? Trouvez le premier cadre qui référence un fichier que vous avez écrit, pas une bibliothèque ou l'environnement d'exécution. Cette ligne est celle où l'erreur s'est manifestée. La cause réelle se trouve parfois un cadre au-dessus, où une valeur erronée a été passée, donc lisez le message en regard de la ligne et suivez les données en arrière si la ligne elle-même semble anodine.

Puis-je faire confiance à un outil d'IA pour expliquer ma trace de pile ? Généralement oui, pour une première lecture rapide. Un bon explicateur de code nommera correctement le type d'erreur et vous dirigera vers la bonne zone bien plus rapidement que de parcourir des forums. Considérez sa correction spécifique comme une hypothèse, cependant : vérifiez que le numéro de ligne correspond au code défaillant et ne collez jamais une méthode ou un paquet suggéré dont vous ne pouvez pas vérifier l'existence.

Pourquoi ma trace ne montre-t-elle que du code de bibliothèque et aucun de mes fichiers ? Cela signifie généralement que vous avez passé une mauvaise entrée à une bibliothèque ou appelé son API incorrectement, donc le plantage se produit dans leur code à cause de vous. Cherchez le cadre limite où votre appel entre dans la bibliothèque et vérifiez les valeurs ou arguments que vous lui avez donnés. La correction se trouve dans votre entrée, même si l'explosion a lieu dans leur code.

Que faire avec une trace de pile asynchrone ou Promise qui semble déconnectée ? Les erreurs asynchrones peuvent apparaître loin de l'endroit où l'appel original a été fait, donc la trace peut sembler courte ou sauter de manière inattendue. Cherchez une promesse non attendue ou une erreur avalée en amont, activez les traces de pile asynchrones si votre environnement d'exécution le permet, et ajoutez un journal juste avant l'await suspect pour confirmer la valeur que vous avez réellement à ce stade.