Гайды

Ошибка 502 Bad Gateway — что значит и как починить: 3 причины

Иллюстрация: курьер стоит у закрытой двери с пакетом в руках

Ты задеплоил приложение, открываешь сайт — «502 Bad Gateway». В логах приложения пусто. И это, кстати, главная подсказка.

Потому что 502 отдаёт не твой код. Его отдаёт прокси, который стоит перед приложением — nginx, Caddy, балансировщик хостинга, Cloudflare. Он честно постучался к твоему приложению и не получил внятного HTTP-ответа.

Вот почему пустые логи — это не «странно», а нормально: до твоего кода запрос не дошёл.

Симптом: почему это точно не баг в коде

Тут есть тонкость, которая сразу отсекает половину гипотез. MDN формулирует её так: если сервер прислал прокси валидный HTTP-ответ с ошибкой, прокси обязан передать его насквозь — а не подменять на 502.

Переведём на человеческий: если бы твой код упал на необработанном исключении, ты бы увидел ошибку 500, а не 502.

502 означает другое — приложение не ответило по правилам HTTP вообще. Не запущено, слушает не там, или оборвало соединение на середине.

Ещё раз, чтобы запомнить: 500 — «мой код упал». 502 — «до кода не дошло». Общая логика кодов разобрана в статье про коды ответа HTTP.

Причина 1. Приложение не запущено или упало

Самая частая, особенно сразу после деплоя. Процесс не поднялся — а прокси об этом не знает и продолжает стучаться в пустоту.

Как проверить. Смотри логи процесса, а не веб-сервера:

systemctl status myapp        # или: docker ps -a
journalctl -u myapp -n 50     # или: docker logs myapp --tail 50
pm2 logs myapp --lines 50

Ищи не последнюю строку, а место, где процесс умер при старте. Типичное: не хватает переменной окружения, синтаксическая ошибка в свежем коде, порт занят.

В логах nginx это выглядит так:

connect() failed (111: Connection refused) while connecting to upstream

Connection refused — приговор однозначный: по этому адресу никто не слушает.

Как починить. Подними процесс и убедись, что он не падает через две секунды (docker ps -a покажет статус Restarting). Если упал на переменных или сборке — смотри разбор почему падает деплой.

Причина 2. Слушает не тот адрес или порт

Процесс жив, Connection refused всё равно есть. Классика, и ловушек тут две.

Ловушка первая: порт. Прокси проксирует на 3000, приложение поднялось на 8080 — потому что взяло значение по умолчанию, а PORT в окружении не оказалось. Проверь оба места, а не одно.

ss -tlnp | grep 3000     # кто вообще слушает этот порт
curl -i localhost:3000   # отвечает ли в обход прокси

Если curl на самом сервере отвечает, а через домен 502 — проблема точно в конфиге прокси. Если и curl не отвечает — в приложении.

Ловушка вторая, коварнее: адрес. Приложение слушает 127.0.0.1, а не 0.0.0.0. На своей машине это незаметно — всё в одном месте. А в Docker 127.0.0.1 внутри контейнера означает «сам этот контейнер», и прокси снаружи не достучится никогда.

app.listen(process.env.PORT || 3000, '0.0.0.0');

Признак именно этой причины: внутри контейнера curl localhost:3000 работает, а снаружи нет. Заодно проверь, что порт вообще опубликован (-p 3000:3000) — и что он не занят кем-то другим, как это бывает.

Причина 3. Процесс умирает во время ответа

Реже, но искать её дольше всех: 502 приходит не на все запросы, а на тяжёлые. Одна страница открывается, другая — нет.

Механика такая: приложение начало отвечать и умерло на середине. Прокси получил обрыв вместо ответа — то есть «невалидный ответ», ровно определение 502. Причины:

  • Убил OOM killer. Контейнеру дали 512 МБ, запрос грузит в память большой файл или выборку из базы. В docker inspect увидишь OOMKilled: true, в dmesg — строку про Out of memory.
  • Воркер перезапустился по таймауту. У gunicorn, puma, unicorn есть свой лимит на длительность запроса, и по нему воркер убивают.
  • Утечка соединений к базе. Пул исчерпан, новые запросы падают.

Как проверить. Открой логи обеих сторон и сопоставь по времени: в момент 502 в логе приложения будет либо обрыв на полуслове, либо запись о рестарте воркера.

Если долго думает — это, скорее всего, 504

Отдельная развилка, которую путают с 502. Когда приложение живо, но отвечает слишком медленно, прокси не ждёт бесконечно. У nginx оба ключевых таймаута по умолчанию — 60 секунд:

proxy_connect_timeout 60s;
proxy_read_timeout 60s;

Молчание дольше минуты — и клиент получит 504 Gateway Timeout: «ответа не было вообще». Разница ровно та же, что в определении MDN: 502 — пришло что-то невалидное, 504 — не пришло ничего.

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

Если у тебя Cloudflare — код скажет больше

Полезная штука, которую мало кто использует. За Cloudflare ты часто увидишь не 502, а один из его собственных кодов, и каждый указывает на конкретное место:

  • 521 Web Server Is Down — origin отказал в соединении. Практически всегда причина 1 или 2 из этой статьи.
  • 522 Connection Timed Out — соединение не установилось. Обычно файрвол режет IP Cloudflare.
  • 523 Origin Is Unreachable — не находит сервер. Смотри DNS и адрес origin.
  • 524 A Timeout Occurred — соединение есть, ответа нет. Это «их 504», причина в скорости обработчика.
  • 520 — origin ответил чем-то, что Cloudflare не смог разобрать.

То есть код уже сузил поиск за тебя. Читай его прежде, чем лезть в конфиги.

Чем 502 отличается от 500?

Местом сбоя. 500 — запрос дошёл до твоего приложения, и там упал код: ищи стек-трейс в логах. 502 — запрос до приложения не дошёл или ответ оборвался: ищи, живо ли оно и на том ли адресе слушает.

Почему локально всё работает?

Потому что локально обычно нет прокси — браузер стучится прямо в приложение. Уходят все три причины сразу: адрес совпадает, портов один, память не ограничена. Чтобы поймать 502 у себя, нужно повторить ту же схему — контейнер с лимитом памяти и nginx перед ним.

Отладка — навык, который строится из вот таких развилок «где именно оборвалось». В KODiQ мы разбираем их на «ты» и по шагам, на живых ошибках.

Стань ИИ-архитектором, а не просто читай об ИИ

Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →