Error

Description

Les erreurs d'exécution entraînent la création et la levée de nouveaux objets Error.

Error est un objet sérialisable, il peut donc être cloné avec structuredClone() ou copié entre Workers en utilisant postMessage().

Types d'erreur

Outre le constructeur générique Error, il existe d'autres constructeurs d'erreur principaux en JavaScript. Pour les exceptions côté client, voir Contrôle du flux d'instructions et gestion des erreurs.

EvalError

Crée une instance représentant une erreur qui se produit concernant la fonction globale eval().

RangeError

Crée une instance représentant une erreur qui se produit lorsqu'une variable ou un paramètre numérique est en dehors de sa plage de validité.

ReferenceError

Crée une instance représentant une erreur qui se produit lors du déréférencement d'une référence invalide.

SyntaxError

Crée une instance représentant une erreur de syntaxe.

TypeError

Crée une instance représentant une erreur qui se produit lorsqu'une variable ou un paramètre n'est pas d'un type valide.

URIError

Crée une instance représentant une erreur qui se produit lorsque encodeURI() ou decodeURI() reçoivent des paramètres invalides.

AggregateError

Crée une instance représentant plusieurs erreurs regroupées dans une seule erreur lorsque plusieurs erreurs doivent être signalées par une opération, par exemple par Promise.any().

InternalError Non standard

Crée une instance représentant une erreur qui se produit lorsqu'une erreur interne du moteur JavaScript est levée. Par exemple « too much recursion ».

Constructeur

Error()

Crée un nouvel objet Error.

Propriétés statiques

Error.stackTraceLimit Non standard

Une propriété numérique non standard qui limite le nombre de trames de pile à inclure dans une trace de pile d'erreur.

Méthodes statiques

Error.captureStackTrace()

Une fonction non standard qui crée la propriété stack sur l'objet fourni.

Error.isError()

Retourne true si l'argument est une erreur, ou false sinon.

Error.prepareStackTrace() Non standard Facultatif

Une fonction non standard qui, si elle est fournie par le code de l'utilisateur·ice, est appelée par le moteur JavaScript pour les exceptions levées, permettant à l'utilisateur·ice de fournir un formatage personnalisé pour les traces de pile. Voir la documentation de l'API V8 Stack Trace ^(angl.).

Propriétés d'instance

Ces propriétés sont définies sur Error.prototype et partagées par toutes les instances de Error.

Error.prototype.constructor

La fonction constructeur qui a créé l'objet d'instance. Pour les instances de Error, la valeur initiale est le constructeur Error.

Error.prototype.name

Représente le nom du type d'erreur. Pour Error.prototype.name, la valeur initiale est "Error". Les sous-classes comme TypeError et SyntaxError fournissent leur propre propriété name.

Error.prototype.stack Non standard

Une propriété non standard pour une trace de pile.

Ces propriétés sont des propriétés propres à chaque instance de Error.

cause

Cause de l'erreur indiquant la raison pour laquelle l'erreur courante est levée — généralement une autre erreur interceptée. Pour les objets Error créés par l'utilisateur·ice, il s'agit de la valeur fournie comme propriété cause du second argument du constructeur.

columnNumber Non standard

Propriété non standard de Mozilla pour le numéro de colonne dans la ligne qui a généré cette erreur.

fileName Non standard

Propriété non standard de Mozilla pour le chemin du fichier qui a généré cette erreur.

lineNumber Non standard

Propriété non standard de Mozilla pour le numéro de ligne dans le fichier qui a généré cette erreur.

message

Message d'erreur. Pour les objets Error créés par l'utilisateur·ice, il s'agit de la chaîne de caractères fournie comme premier argument du constructeur.

Méthodes d'instance

Error.prototype.toString()

Retourne une chaîne de caractères représentant l'objet défini. Redéfinit la méthode Object.prototype.toString().

Exemples

Déclenchement d'une erreur générique

On crée habituellement un objet Error dans l'intention de le déclencher en utilisant le mot-clé throw. L'erreur peut ensuite être interceptée et gérée en utilisant la construction try...catch :

try {
  throw new Error("Oups !");
} catch (e) {
  console.error(`${e.name} : ${e.message}`);
}

Gestion d'une erreur spécifique

Vous pouvez choisir de gérer uniquement certains types d'erreur en testant le type de l'erreur avec le mot-clé instanceof :

try {
  toto.truc();
} catch (e) {
  if (e instanceof EvalError) {
    console.error(`${e.name} : ${e.message}`);
  } else if (e instanceof RangeError) {
    console.error(`${e.name} : ${e.message}`);
  }
  // etc.
  else {
    // Si aucun cas ne correspond, on laisse l'erreur non gérée
    throw e;
  }
}

Distinguer des erreurs semblables

Il arrive parfois que des erreurs semblables (type et message identiques) nécessitent des traitements différents.

Si vous ne maîtrisez pas l'origine des erreurs, vous pouvez les intercepter et renvoyer de nouveaux objets Error avec des messages plus spécifiques. L'erreur d'origine doit être passée au nouveau Error dans le paramètre options du constructeur comme propriété cause. Cela garantit que l'erreur d'origine et la pile d'appels sont disponibles pour les blocs try/catch de plus haut niveau.

Dans l'exemple qui suit, on illustre ceci pour deux méthodes qui échoueraient avec des erreurs similaires (echecUneFacon() et echecAutreFacon()) :

function faireTruc() {
  try {
    echecUneFacon();
  } catch (err) {
    throw new Error("Echoue d'une certaine façon", { cause: err });
  }
  try {
    echecAutreFacon();
  } catch (err) {
    throw new Error("Echoue d'une autre façon", { cause: err });
  }
}

try {
  faireTruc();
} catch (err) {
  switch (err.message) {
    case "Echoue d'une certaine façon":
      gererUneFacon(err.cause);
      break;
    case "Echoue d'une autre façon":
      gererUneAutreFacon(err.cause);
      break;
  }
}

Les types d'erreur personnalisés peuvent également utiliser la propriété cause, à condition que le constructeur des sous-classes transmette le paramètre options lors de l'appel à super(). Le constructeur de la classe de base Error() lira options.cause et définira la propriété cause sur la nouvelle instance d'erreur.

class MonErreur extends Error {
  constructor(message, options) {
    // Il faut passer l'argument `options` en second paramètre
    // pour que la propriété "cause" soit initialisée.
    super(message, options);
  }
}

console.log(new MonErreur("test", { cause: new Error("cause") }).cause);
// Error: cause

Types d'erreur personnalisés

Il est possible de définir ses propres types d'erreur dérivés de Error et d'utiliser alors throw new MonErreur() et instanceof MonErreur pour vérifier le type d'erreur lors du traitement. Cela permet d'avoir un code plus concis et cohérent pour le traitement des erreurs.

Voir « Quelle est une bonne façon d'étendre Error en JavaScript ? » ^(angl.) sur StackOverflow pour une discussion détaillée.

class ErreurSpecifique extends Error {
  constructor(toto = "truc", ...params) {
    // On passe les arguments restants (y compris ceux
    // de l'éditeur tiers) au constructeur parent
    super(...params);

    // On garde la pile d'appels de l'erreur
    // Uniquement disponible pour V8
    if (Error.captureStackTrace) {
      Error.captureStackTrace(this, ErreurSpecifique);
    }

    this.name = "ErreurSpecifique";
    // Les informations de débogage spécifiques
    this.toto = toto;
    this.date = new Date();
  }
}

try {
  throw new ErreurSpecifique("truc", "trucMessage");
} catch (e) {
  console.error(e.name); // ErreurSpecifique
  console.error(e.toto); // truc
  console.error(e.message); // trucMessage
  console.error(e.stack); // stacktrace
}

Spécifications

Compatibilité des navigateurs

Voir aussi

• Prothèse d'émulation pour Error avec la prise en charge de cause ^(angl.)
• Prothèse d'émulation es-shims de Error cause ^(angl.)
• L'instruction throw
• L'instruction try...catch
• L'API de trace de pile ^(angl.) dans la documentation V8