Uncaught TypeError — частые причины и исправление

Uncaught TypeError — самая частая ошибка JavaScript в браузере. Она значит, что код сделал с значением то, чего с ним делать нельзя: прочитал свойство у undefined, вызвал как функцию то, что функцией не является, перебрал в цикле не массив. Слово Uncaught означает, что ни один try/catch ошибку не поймал, и она дошла до браузера. Если ошибка случилась в промисе, браузер пишет Uncaught (in promise) TypeError.

Ниже — самые частые варианты с причиной и исправлением, почему в продакшене стек такой ошибки нечитаем и как узнать, что она случается у реальных посетителей.

Cannot read properties of undefined (reading 'x')

Самый частый вариант. Код обращается к свойству объекта, которого нет:

js
const user = undefined;
user.name; // TypeError: Cannot read properties of undefined (reading 'name')

Тот же случай в других браузерах и старых версиях Chrome выглядит иначе:

Браузер Текст
Chrome, Edge Cannot read properties of undefined (reading 'name')
Chrome до версии 91 Cannot read property 'name' of undefined
Firefox can't access property "name", user is undefined
Safari undefined is not an object (evaluating 'user.name')

Вариант с null — Cannot read properties of null (reading 'x') — чаще всего значит, что document.querySelector или getElementById не нашёл элемент: скрипт выполнился до того, как элемент появился в DOM, или в селекторе опечатка.

Типичные причины:

  • данные с сервера ещё не пришли, а компонент уже рисуется;
  • API вернул другую структуру: data.items вместо data.results, или поля нет у части записей;
  • опечатка в имени свойства;
  • элемент массива по индексу, которого нет: list[0].id у пустого списка.

Как исправить. Опциональная цепочка ?. и значение по умолчанию ??:

js
const name = user?.profile?.name ?? 'Гость';
const firstId = list[0]?.id;
const count = data?.items?.length ?? 0;

В React — не рисовать то, чего ещё нет:

jsx
function Orders() {
  const { data, isLoading } = useOrders();
  if (isLoading) return <Spinner />;
  if (!data) return null;
  return data.items.map((o) => <OrderRow key={o.id} order={o} />);
}

Не прячьте ошибку за ?. везде подряд. Если user обязан быть после входа, а его нет, это баг в логике, и пустой экран без ошибки будет хуже. Опциональная цепочка нужна там, где отсутствие значения — нормальное состояние.

x is not a function

js
const items = { a: 1 };
items.map((x) => x); // TypeError: items.map is not a function

Причины: вызвали метод массива у объекта или строки; API вернул { items: [...] }, а код ждал массив; функция не экспортирована или импортирована не так (import foo from вместо import { foo } from); колбэк не передали в компонент; имя функции перекрыто переменной.

Как исправить. Проверьте, что лежит в значении, — console.log(typeof x, x) или точка останова. Для данных извне — проверка типа:

js
const list = Array.isArray(data) ? data : data?.items ?? [];
onChange?.(value); // колбэк необязательный

Cannot set properties of undefined

js
const state = {};
state.user.name = 'Анна'; // TypeError: Cannot set properties of undefined (setting 'name')

Записывают в свойство объекта, которого нет. Опциональная цепочка при записи не работает: state.user?.name = 'Анна' — синтаксическая ошибка. Создайте объект заранее:

js
state.user ??= {};
state.user.name = 'Анна';
// или сразу целиком
state.user = { ...state.user, name: 'Анна' };

x is not iterable

js
const [a, b] = undefined;          // TypeError: undefined is not iterable
const obj = { a: 1 };
for (const item of obj) {}         // TypeError: obj is not iterable

Появляется при for...of, деструктуризации массива, ...spread в массив, Promise.all, new Map() — всё это требует перебираемое значение. Частый случай в React — хук, который возвращает объект, а его разбирают как массив: const [data] = useQuery().

Как исправить: подставьте пустой массив по умолчанию, а для объектов используйте Object.entries:

js
for (const item of data?.items ?? []) {}
for (const [key, value] of Object.entries(obj)) {}
const [first = null] = list ?? [];

Assignment to constant variable

js
const total = 0;
total += 10; // TypeError: Assignment to constant variable.

Переменная объявлена через const, а её пытаются переприсвоить. Если значение должно меняться — объявите через let. Изменять содержимое const-объекта или массива можно: const list = []; list.push(1) работает, нельзя только присвоить переменной новое значение.

Порядок загрузки данных

Многие TypeError в продакшене — не опечатки, а гонки: код выполнился раньше, чем появилось значение. Разработчик этого не видит, потому что у него быстрый интернет и данные в кеше. У посетителя на мобильной сети ответ API приходит позже, чем отрисовывается компонент.

Проверьте:

  • скрипты, которые работают с DOM, подключены с defer или запускаются после DOMContentLoaded;
  • компонент умеет рисовать состояние «загрузка» и «нет данных», а не только «данные есть»;
  • данные из localStorage и URL могут отсутствовать или быть старого формата — их нужно проверять;
  • ответ с ошибкой (500, 401) не разбирается как успешный: проверяйте response.ok до response.json().

Чтобы увидеть гонку у себя, включите в DevTools → Network замедление сети (Slow 4G) и пройдите сценарий заново.

Почему в продакшене стек TypeError нечитаем

В собранном приложении код минифицирован, и ошибка выглядит так:

text
TypeError: Cannot read properties of undefined (reading 'map')
    at Xo (https://example.com/assets/index-B3xk9.js:1:48213)
    at Ui (https://example.com/assets/index-B3xk9.js:1:91877)

Имя функции Xo, весь код в одной строке — по такому стеку непонятно, где ошибка. Исправляют это source maps — карты соответствия собранного кода исходному. С картой тот же стек превращается в OrderList (src/pages/Orders.tsx:42) с кодом вокруг строки.

Выкладывать карты на сайт необязательно: их можно собирать в режиме hidden (без ссылки в бандле) и загружать только в систему мониторинга. Так исходный код не виден посетителям.

Как узнать, что TypeError случается у реальных посетителей

Ошибку, которая воспроизводится у вас, вы почините сами. Опаснее те, что случаются только у части людей: в Safari, у пользователей со старыми данными в localStorage, на медленной сети. Посетитель видит неработающую кнопку и уходит, а в вашей консоли пусто.

Пакет @nablops/react (или @nablops/browser без React) отправляет в NablOps необработанные ошибки (window.onerror) и отклонённые промисы из браузеров посетителей, а ошибки рендера — через nabl.ErrorBoundary. В NablOps на вкладке «Ошибки» фронтенда одинаковые случаи собраны в одну запись со счётчиком. На странице ошибки видно браузеры, системы, страницы и затронутые сессии. Если приложение передаёт nabl.setUser({ id }), видно и кого задела ошибка.

С загруженными source maps ошибка группируется по месту в коде, а не по тексту. Поэтому одна и та же ошибка в Chrome («Cannot read properties of undefined») и Safari («undefined is not an object») — одна запись, а не две. Для Vite карты загружает @nablops/vite-plugin, для других сборщиков — @nablops/cli.

Чтобы понять, почему значение оказалось undefined, смотрите сессию: какие страницы человек открывал, на что нажимал, что писала консоль и какие запросы к API падали перед ошибкой. Если ошибка случилась сразу после упавшего запроса, со страницы ошибки можно перейти в трассу этого запроса на бэкенде — если в проекте настроена трассировка.

Разобрать ошибку можно и через ИИ-ассистента: он видит стек с исходным кодом, сессию и связанный запрос.

Что дальше

Попробуйте NablOps

Первый сервер или стек подключается за пару минут. Бесплатно в раннем доступе.

Создать аккаунт

Нашли неточность или не хватает ответа? Напишите в поддержку