Uncaught TypeError — частые причины и исправление
Uncaught TypeError — самая частая ошибка JavaScript в браузере. Она значит, что код сделал с значением то, чего с ним делать нельзя: прочитал свойство у undefined, вызвал как функцию то, что функцией не является, перебрал в цикле не массив. Слово Uncaught означает, что ни один try/catch ошибку не поймал, и она дошла до браузера. Если ошибка случилась в промисе, браузер пишет Uncaught (in promise) TypeError.
Ниже — самые частые варианты с причиной и исправлением, почему в продакшене стек такой ошибки нечитаем и как узнать, что она случается у реальных посетителей.
Cannot read properties of undefined (reading 'x')
Самый частый вариант. Код обращается к свойству объекта, которого нет:
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у пустого списка.
Как исправить. Опциональная цепочка ?. и значение по умолчанию ??:
const name = user?.profile?.name ?? 'Гость';
const firstId = list[0]?.id;
const count = data?.items?.length ?? 0;В React — не рисовать то, чего ещё нет:
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
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) или точка останова. Для данных извне — проверка типа:
const list = Array.isArray(data) ? data : data?.items ?? [];
onChange?.(value); // колбэк необязательныйCannot set properties of undefined
const state = {};
state.user.name = 'Анна'; // TypeError: Cannot set properties of undefined (setting 'name')Записывают в свойство объекта, которого нет. Опциональная цепочка при записи не работает: state.user?.name = 'Анна' — синтаксическая ошибка. Создайте объект заранее:
state.user ??= {};
state.user.name = 'Анна';
// или сразу целиком
state.user = { ...state.user, name: 'Анна' };x is not iterable
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:
for (const item of data?.items ?? []) {}
for (const [key, value] of Object.entries(obj)) {}
const [first = null] = list ?? [];Assignment to constant variable
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 нечитаем
В собранном приложении код минифицирован, и ошибка выглядит так:
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 падали перед ошибкой. Если ошибка случилась сразу после упавшего запроса, со страницы ошибки можно перейти в трассу этого запроса на бэкенде — если в проекте настроена трассировка.
Разобрать ошибку можно и через ИИ-ассистента: он видит стек с исходным кодом, сессию и связанный запрос.
Что дальше
- Мониторинг ошибок React — как подключить
@nablops/react. - Source maps — читаемый стек вместо минифицированного бандла.
- Сессии и пользователи — что делал посетитель перед ошибкой.
- Error Boundary в React — экран вместо белой страницы при ошибке рендера.
Первый сервер или стек подключается за пару минут. Бесплатно в раннем доступе.
Нашли неточность или не хватает ответа? Напишите в поддержку