Error

Об'єкти Error (помилка) викидаються, коли трапляється помилка часу виконання. Об'єкт Error також може використовуватися як базовий об'єкт для винятків, визначених користувачем.

Опис

Помилки часу виконання призводять до створення і викидання нових об'єктів Error.

Error – це серіалізовний об'єкт, тож він може бути клонований за допомогою structuredClone() і скопійований між воркерами за допомогою postMessage().

Типи помилок

Окрім узагальненого конструктора Error, ядро JavaScript містить інші конструктори помилок. Про помилки клієнтського боку читайте Інструкції обробки винятків.

EvalError

Створює примірник, що представляє помилку, котра трапляється відносно глобальної функції eval().

RangeError

Створює примірник, що представляє помилку, котра трапляється, коли числова змінна або параметр знаходяться поза своїм допустимим діапазоном.

ReferenceError

Створює примірник, що представляє помилку, котра трапляється при звертанні за недійсним посиланням.

SyntaxError

Створює примірник, що представляє помилку синтаксису.

TypeError

Створює примірник, що представляє помилку, котра трапляється, коли змінна або параметр має невідповідний тип.

URIError

Створює примірник, що представляє помилку, котра трапляється, коли в encodeURI() або decodeURI() передано невідповідні параметри.

AggregateError

Створює примірник, що представляє кілька помилок, загорнутих в одну помилку, коли операція потребує звітування про декілька помилок, наприклад, Promise.any().

InternalError

Створює примірник, що представляє помилку, котра трапляється тоді, коли викидається внутрішня помилка рушія JavaScript. Наприклад, "забагато рекурсії".

Конструктор

Error()

Створює новий об'єкт Error.

Статичні методи

Error.captureStackTrace()

Нестандартна функція V8, що створює на примірнику Error властивість stack.

Error.stackTraceLimit

Нестандартна числова властивість V8, що обмежує те, скільки фреймів стека включається в трасування стека помилки.

Error.prepareStackTrace() Необов'язкове

Нестандартна функція V8, котра, якщо задана користувацьким кодом, викликається рушієм V8 для викинутих винятків, даючи користувачеві змогу задавати власне форматування трасувань стека.

Властивості примірника

Ці властивості означені на Error.prototype і є спільними для всіх примірників Error.

Error.prototype.constructor

Функція-конструктор, що створила об'єкт-примірник. Для примірників Error початковим значенням є конструктор Error.

Error.prototype.name

Представляє назву типу помилки. Для Error.prototype.name початковим значенням є "Error". Підкласи, наприклад, TypeError і SyntaxError, мають власні властивості name.

Error.prototype.stack

Нестандартна властивість для трасування стека.

Ці властивості є власними властивостями кожного окремого примірника Error.

cause

Причина помилки, що вказує на причину викидання помилки – зазвичай інша, перехоплена помилка. Для створених користувачем об'єктів Error, це значення, що задається властивістю cause другого аргументу конструктора.

columnNumber

Нестандартна властивість Mozilla для номера колонки в рядку, що спричинила помилку.

fileName

Нестандартна властивість Mozilla для шляху до файлу, що спричинив помилку.

lineNumber

Нестандартна властивість Mozilla для номера рядка у файлі, що спричинив помилку.

message

Повідомлення помилки. Для створених користувачем об'єктів Error це рядок, заданий як перший аргумент конструктора.

Методи примірника

Error.prototype.toString()

Повертає рядок, що представляє заданий об'єкт. Заміщує метод Object.prototype.toString().

Приклади

Викидання узагальненої помилки

Зазвичай об'єкт Error створюють з наміром викинути його за допомогою ключового слова throw. Обробити помилку можна за допомогою конструкції try...catch:

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

Обробка помилок конкретного типу

Обробляти помилки лише певного типу можна шляхом перевірки типу помилки за допомогою ключового слова instanceof:

try {
  foo.bar();
} catch (e) {
  if (e instanceof EvalError) {
    console.error(`${e.name}: ${e.message}`);
  } else if (e instanceof RangeError) {
    console.error(`${e.name}: ${e.message}`);
  }
  // тощо.
  else {
    // Якшо жодна з перевірок не спрацювала – залишити Error без обробки
    throw e;
  }
}

Розрізнення подібних помилок

Іноді блок коду може зазнавати невдачі з причин, що потребують різної обробки, але викидають дуже подібні помилки (наприклад, з однаковими типом і повідомленням).

Якщо немає контролю над вихідними помилками, що викидаються, то один з варіантів – перехоплювати їх і викидати нові об'єкти Error, що мають конкретніші повідомлення. Вихідна помилка повинна бути передана в новий Error у параметр options конструктора як його властивість cause. Це дає впевненість щодо того, що блокам try-catch вищого рівня доступні вихідні помилка та трасування стека.

Приклад нижче показує це для двох методів, що інакше зазнавали б невдачі з подібними помилками (doFailSomeWay() і doFailAnotherWay()):

function doWork() {
  try {
    doFailSomeWay();
  } catch (err) {
    throw new Error("Якось не вийшло", { cause: err });
  }
  try {
    doFailAnotherWay();
  } catch (err) {
    throw new Error("Не вийшло якось інакше", { cause: err });
  }
}

try {
  doWork();
} catch (err) {
  switch (err.message) {
    case "Якось не вийшло":
      handleFailSomeWay(err.cause);
      break;
    case "Не вийшло якось інакше":
      handleFailAnotherWay(err.cause);
      break;
  }
}

Примітка: При написанні бібліотеки краще використовувати причину помилки для розрізнення різних помилок, що породжуються, а не просити користувачів бібліотеки розбирати повідомлення помилок. Шукайте приклад на сторінці причини помилки.

Власні типи помилок також можуть використовувати властивість cause, за умови, що конструктор підкласів передає параметр options при виклику super(). Конструктор базового класу Error() зчитає options.cause та означить на новому примірнику помилки властивість cause.

class MyError extends Error {
  constructor(message, options) {
    // Необхідно передавати `options` як другий параметр, аби встановити властивість "cause".
    super(message, options);
  }
}

console.log(new MyError("перевірка", { cause: new Error("причина") }).cause);
// Error: причина

Власні типи помилок

Може з'явитись потреба означити власні типи помилок, похідні від Error, аби мати змогу виконувати throw new MyError() і використовувати instanceof MyError для перевірки ґатунку помилки в обробнику помилок. Такий підхід призводить до чистішого та сталішого коду обробки помилок.

Читайте заглиблену дискусію на StackOverflow – "Що є добрим способом розширювати Error у JavaScript?".

Застереження: Вбудоване створення підкласів не може бути надійно трансльовано у код до ES6, тому що немає способу сконструювати базовий клас із конкретним значенням new.target без Reflect.construct(). Необхідне додаткове налаштування або ручний виклик Object.setPrototypeOf(this, CustomError.prototype) у кінці конструктора; без цього сконструйований примірник не буде примірником CustomError. Більше інформації – у ЧаПах TypeScript.

Примітка: Частина браузерів включає конструктор CustomError у трасування стека при використанні класів ES2015.

class CustomError extends Error {
  constructor(foo = "bar", ...params) {
    // Передача решти аргументів (включно зі специфічними щодо виробника браузера) батьківському конструктору
    super(...params);

    // Збереження коректного трасування стека з місця, де була викинута наша помилка (доступно лише у V8)
    if (Error.captureStackTrace) {
      Error.captureStackTrace(this, CustomError);
    }

    this.name = "CustomError";
    // Власна інформація для зневадження
    this.foo = foo;
    this.date = new Date();
  }
}

try {
  throw new CustomError("baz", "bazMessage");
} catch (e) {
  console.error(e.name); // CustomError
  console.error(e.foo); // baz
  console.error(e.message); // bazMessage
  console.error(e.stack); // stacktrace
}

Специфікації

Сумісність із браузерами

desktop mobile server
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on iOS Samsung Internet Deno Node.js
Error
Chrome Full support 1
Edge Full support 12
Firefox Full support 1
Internet Explorer Full support 6
Opera Full support 4
Safari Full support 1
WebView Android Full support 1
Chrome Android Full support 18
Firefox for Android Full support 4
Opera Android Full support 10.1
Safari on iOS Full support 1
Samsung Internet Full support 1.0
Deno Full support 1.0
Node.js Full support 0.10.0
Error() constructor Chrome Full support 1
Edge Full support 12
Firefox Full support 1
Internet Explorer Full support 6
Opera Full support 4
Safari Full support 1
WebView Android Full support 1
Chrome Android Full support 18
Firefox for Android Full support 4
Opera Android Full support 10.1
Safari on iOS Full support 1
Samsung Internet Full support 1.0
Deno Full support 1.0
Node.js Full support 0.10.0
fileName parameter
Нестандартне
Chrome No support Ні
Edge No support Ні
Firefox Full support 1
Internet Explorer No support Ні
Opera No support Ні
Safari No support Ні
WebView Android No support Ні
Chrome Android No support Ні
Firefox for Android Full support 4
Opera Android No support Ні
Safari on iOS No support Ні
Samsung Internet No support Ні
Deno No support Ні
Node.js No support Ні
lineNumber parameter
Нестандартне
Chrome No support Ні
Edge No support Ні
Firefox Full support 1
Internet Explorer No support Ні
Opera No support Ні
Safari No support Ні
WebView Android No support Ні
Chrome Android No support Ні
Firefox for Android Full support 4
Opera Android No support Ні
Safari on iOS No support Ні
Samsung Internet No support Ні
Deno No support Ні
Node.js No support Ні
options.cause parameter
Chrome Full support 93
Edge Full support 93
Firefox Full support 91
Internet Explorer No support Ні
Opera Full support 79
Safari Full support 15
WebView Android Full support 93
Chrome Android Full support 93
Firefox for Android Full support 91
Opera Android No support Ні
Safari on iOS Full support 15
Samsung Internet Full support 17.0
Deno Full support 1.13
Node.js Full support 16.9.0
cause
Chrome Full support 93
Edge Full support 93
Firefox Full support 91
Internet Explorer No support Ні
Opera No support Ні
Safari Full support 15
WebView Android Full support 93
Chrome Android Full support 93
Firefox for Android Full support 91
Opera Android No support Ні
Safari on iOS Full support 15
Samsung Internet Full support 17.0
Deno Full support 1.13
Node.js Full support 16.9.0
columnNumber
Нестандартне
Chrome No support Ні
Edge No support Ні
Firefox Full support 1
Internet Explorer No support Ні
Opera No support Ні
Safari No support Ні
WebView Android No support Ні
Chrome Android No support Ні
Firefox for Android Full support 4
Opera Android No support Ні
Safari on iOS No support Ні
Samsung Internet No support Ні
Deno No support Ні
Node.js No support Ні
fileName
Нестандартне
Chrome No support Ні
Edge No support Ні
Firefox Full support 1
Internet Explorer No support Ні
Opera No support Ні
Safari No support Ні
WebView Android No support Ні
Chrome Android No support Ні
Firefox for Android Full support 4
Opera Android No support Ні
Safari on iOS No support Ні
Samsung Internet No support Ні
Deno No support Ні
Node.js No support Ні
lineNumber
Нестандартне
Chrome No support Ні
Edge No support Ні
Firefox Full support 1
Internet Explorer No support Ні
Opera No support Ні
Safari No support Ні
WebView Android No support Ні
Chrome Android No support Ні
Firefox for Android Full support 4
Opera Android No support Ні
Safari on iOS No support Ні
Samsung Internet No support Ні
Deno No support Ні
Node.js No support Ні
message Chrome Full support 1
Edge Full support 12
Firefox Full support 1
Internet Explorer Full support 6
Opera Full support 5
Safari Full support 1
WebView Android Full support 1
Chrome Android Full support 18
Firefox for Android Full support 4
Opera Android Full support 10.1
Safari on iOS Full support 1
Samsung Internet Full support 1.0
Deno Full support 1.0
Node.js Full support 0.10.0
name Chrome Full support 1
Edge Full support 12
Firefox Full support 1
Internet Explorer Full support 6
Opera Full support 4
Safari Full support 1
WebView Android Full support 1
Chrome Android Full support 18
Firefox for Android Full support 4
Opera Android Full support 10.1
Safari on iOS Full support 1
Samsung Internet Full support 1.0
Deno Full support 1.0
Node.js Full support 0.10.0
Error is serializable
Chrome Full support 77
Edge Full support 79
Firefox No support Ні
footnote
Internet Explorer No support Ні
Opera Full support 64
Safari No support Ні
WebView Android Full support 77
Chrome Android Full support 77
Firefox for Android No support Ні
footnote
Opera Android Full support 55
Safari on iOS No support Ні
Samsung Internet Full support 12.0
Deno No support Ні
Node.js No support Ні
stack
Нестандартне
Chrome Full support 3
Edge Full support 12
Firefox Full support 1
Internet Explorer Full support 10
Opera Full support 10.5
Safari Full support 6
WebView Android Full support 37
Chrome Android Full support 18
Firefox for Android Full support 4
Opera Android Full support 11
Safari on iOS Full support 6
Samsung Internet Full support 1.0
Deno Full support 1.0
Node.js Full support 0.10.0
toString Chrome Full support 1
Edge Full support 12
Firefox Full support 1
Internet Explorer Full support 6
Opera Full support 4
Safari Full support 1
WebView Android Full support 1
Chrome Android Full support 18
Firefox for Android Full support 4
Opera Android Full support 10.1
Safari on iOS Full support 1
Samsung Internet Full support 1.0
Deno Full support 1.0
Node.js Full support 0.10.0

Дивіться також