getaddrinfo ENOTFOUND: что означает и как исправить в Node.js и Postman

hannadev

Ошибка getaddrinfo ENOTFOUND в Node.js - это частая проблема при работе с сетевыми запросами. Она возникает, когда система не может найти IP-адрес по указанному доменному имени. В этой статье разберем, почему она появляется в Node.js и Postman, и покажем простые способы исправления.

Знание этой ошибки поможет быстро восстановить работу API, баз данных или внешних сервисов. Мы рассмотрим типичные сценарии из практики и пошаговые решения. Это сэкономит часы отладки для бэкендеров и фронтендеров.

Что значит ошибка getaddrinfo ENOTFOUND

Ошибка getaddrinfo ENOTFOUND сигнализирует о неудаче в DNS-разрешении. Функция getaddrinfo из стандартной библиотеки Node.js пытается преобразовать hostname (например, api.nasa.gov) в IP-адрес, но не находит его. Это происходит на уровне системы, до установления соединения.

Типичные случаи: неверный домен в коде, проблемы с корпоративным DNS, прокси-серверы или временные сбои у провайдера. В Node.js ошибка часто всплывает при https.get(), axios или подключении к базам данных. В Postman она мешает тестировать API из-за локальных сетевых ограничений. Проблема усугубляется в контейнерах Docker или на VPS с кастомным DNS.

Вот основные причины:

Неверный hostname: опечатка в домене или устаревший URL.
DNS-проблемы: корпоративный фаервол блокирует запросы или DNS-сервер не отвечает.
Прокси и VPN: настройки сети перенаправляют трафик неправильно.
IPv6-конфликты: Node.js пытается использовать IPv6, но сервер поддерживает только IPv4.

Причина	Симптомы	Где встречается
Опечатка в домене	ENOTFOUND для несуществующего хоста	Код Node.js, Postman
Корпоративный прокси	Работает в браузере, не в Node	Офисные сети
IPv6-проблемы	Локальный ping работает, запрос - нет	Современные ОС
Неправильный Host header	Axios с кастомными заголовками	Микросервисы

Как исправить в Node.js: базовые шаги

В Node.js ошибка часто связана с опциями запроса или системными настройками. Сначала проверьте, открывается ли URL в браузере - если нет, проблема в сети. Затем убедитесь, что hostname правильный, без лишних портов или путей в поле host.

Частая ошибка - указание полного URL в options.path вместо чистого пути. Например, в https.get() options должны содержать только hostname и path отдельно. Еще один подвох - интерполяция переменных в шаблонных строках без экранирования. После базовой проверки переходите к принудительному IPv4 или прокси-настройкам. Это решает 80% случаев.

Пошаговое исправление:

Проверьте ping hostname в терминале - если не отвечает, проблема в DNS.
Используйте family: 4 в options для принуждения IPv4:

const options = {
  hostname: 'api.nasa.gov',
  port: 443,
  path: '/insight_weather/?api_key=your_key',
  family: 4  // Только IPv4
};

Для axios добавьте dns: false или используйте IP вместо домена.
Настройте прокси через http_proxy переменные окружения.

Если используете axios, проверьте Host header - он может вызывать повторный DNS-lookup.

Решения для Postman и продвинутые случаи

В Postman ошибка ENOTFOUND появляется при импорте коллекций или прямых запросах к внутренним серверам. Часто это из-за системного прокси или VPN, который Postman не подхватывает автоматически. В корпоративной среде добавьте прокси в настройки Postman: File > Settings > Proxy.

Продвинутые сценарии включают Docker-контейнеры, где DNS контейнера не видит внешние хосты. Укажите --dns 8.8.8.8 при запуске или добавьте в docker-compose. В SendGrid или Firebase Functions проблема в конфигурации SMTP-хоста - используйте IP или проверьте config(). Для баз данных вроде MongoDB добавьте useUnifiedTopology: true и правильный connection string.

Частые фиксы для специальных случаев:

Docker: docker run --dns=8.8.8.8 your-image.
Postman с прокси: Вклю System Proxy или укажите manual: http://proxy:port.
Axios с Host header: Удалите или замените на IP: headers: { host: '127.0.0.1' }.
Firebase/SendGrid: Проверьте functions.config().sendgrid.key и SMTP-хост.

Инструмент	Быстрое решение	Альтернатива
Node.js	family: 4	Использовать IP
Postman	System Proxy	cURL в терминале
Docker	–dns 8.8.8.8	hosts файл
Axios	dns: false	node-fetch

Когда ошибка не уходит: отладка и альтернативы

Если стандартные шаги не помогли, запустите nslookup hostname для проверки DNS. В корпоративной сети обратитесь к сисадмину - возможно, домен в черном списке. Логируйте полный стек-трейс: err.syscall, err.hostname, err.code дают подсказки.

Альтернативы getaddrinfo - библиотеки вроде dns.promises для ручного разрешения или node-fetch вместо https. В продакшене добавьте retry-логику с exponential backoff. Тестируйте на разных сетях, чтобы исключить локальные проблемы.

Что проверить в крайнем случае:

resolv.conf файл в Linux/Mac.
Firewall правила: ufw status или Windows Defender.
Перезапуск Node.js с --trace-warnings.

Сетевые запросы без неожиданных сбоев

Ошибка getaddrinfo ENOTFOUND учит осторожности с DNS в коде. Всегда тестируйте хосты заранее и имейте план B с IP-адресами. В Node.js и Postman комбинация family: 4, правильных options и прокси-режима закроет большинство дыр.

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