gunicorn: Worker failed to boot и App failed to load — приложение не запускается
gunicorn запустил рабочий процесс, а тот не смог загрузить ваше приложение, и gunicorn остановился. Строка Reason — только итог: настоящая причина записана в журнале выше неё.
Содержание 8
Как выглядит ошибка
gunicorn пишет журнал строками: в квадратных скобках дата, номер процесса и уровень сообщения. Если приложение не загрузилось, журнал заканчивается так:
[2026-10-22 10:15:04 +0300] [1234] [INFO] Shutting down: Master
[2026-10-22 10:15:04 +0300] [1234] [INFO] Reason: Worker failed to boot.Вместо Worker failed to boot. бывает App failed to load.. В gunicorn 25.1.0 из Ubuntu 26.04 обе строки идут с уровнем ERROR, а не INFO. После них gunicorn завершается, и приложение перестаёт отвечать; если перед ним стоит nginx, он показывает 502 Bad Gateway. Тексты сверены с исходным кодом gunicorn 20.1.0 и 25.1.0 — эти версии ставятся из пакетов Ubuntu 24.04 и 26.04. Если gunicorn поставлен через pip в окружение venv, версия может быть другой.
Что значат две причины
| Строка | Что случилось |
|---|---|
Reason: Worker failed to boot. | при загрузке приложения Python выдал ошибку: нет библиотеки, ошибка в коде, нет прав на файл. Выше в журнале — строка Exception in worker process и сообщение Python |
Reason: App failed to load. | файл приложения загрузился, но gunicorn не нашёл в нём само приложение: не то имя в команде запуска. Выше в журнале — строка без даты, например Failed to find attribute 'application' in 'app'. |
Шаг 1. Найдите первую ошибку
Откройте последние строки журнала службы (про journalctl):
sudo journalctl -u myapp -n 50В журнале systemd перед каждой строкой стоят ещё дата, имя сервера и имя программы — в примерах ниже они убраны. Так выглядит Worker failed to boot в gunicorn 20.1.0, когда он не находит библиотеку flask:
[2026-10-22 10:15:03 +0300] [1236] [INFO] Booting worker with pid: 1236
[2026-10-22 10:15:03 +0300] [1236] [ERROR] Exception in worker process
Traceback (most recent call last):
…
File "/home/ivan/myapp/app.py", line 1, in <module>
from flask import Flask
ModuleNotFoundError: No module named 'flask'
[2026-10-22 10:15:03 +0300] [1236] [INFO] Worker exiting (pid: 1236)
[2026-10-22 10:15:04 +0300] [1234] [INFO] Shutting down: Master
[2026-10-22 10:15:04 +0300] [1234] [INFO] Reason: Worker failed to boot.Нужная строка — последняя строка сообщения Python перед Worker exiting, здесь ModuleNotFoundError: No module named 'flask'. Строка File над ней показывает файл и номер строки в вашем коде. gunicorn 25.1.0 после сообщения Python пишет текст ошибки ещё раз — отдельной строкой без даты.
А так выглядит App failed to load:
[2026-10-22 10:15:03 +0300] [1236] [INFO] Booting worker with pid: 1236
Failed to find attribute 'application' in 'app'.
[2026-10-22 10:15:03 +0300] [1236] [INFO] Worker exiting (pid: 1236)
[2026-10-22 10:15:04 +0300] [1234] [INFO] Shutting down: Master
[2026-10-22 10:15:04 +0300] [1234] [INFO] Reason: App failed to load.Если в журнале ничего нет, запустите gunicorn вручную из папки проекта — ошибка появится прямо на экране:
cd /home/ivan/myapp
venv/bin/gunicorn app:appЗдесь venv — окружение в папке проекта, а app:app — файл app.py и объект app в нём; подставьте свои. Остановить gunicorn — Ctrl+C.
Шаг 2. Исправьте причину
Найдите в таблице строку, похожую на вашу:
| Строка в журнале | Что случилось | Что сделать |
|---|---|---|
Failed to find attribute 'application' in 'app'. | в команде нет объекта после двоеточия, и gunicorn ищет объект application, а в файле его нет | допишите объект через двоеточие: для Flask с app = Flask(__name__) в файле app.py — app:app |
Failed to find attribute 'app' in 'myproject.wsgi'. | в файле нет объекта с таким именем | для Django пишите myproject.wsgi без двоеточия: объект в wsgi.py называется application |
Failed to find application, did you mean 'app:app'? | в команде имя файла с .py | уберите .py: app:app, а не app.py:app |
Failed to find application object: 'create_app()' | функция, которая создаёт приложение, ничего не вернула | допишите в конце функции return app |
Application object must be callable. | после двоеточия указан объект, который не является приложением | проверьте имя после двоеточия |
ModuleNotFoundError: No module named 'flask' | gunicorn запущен не тем Python: например, gunicorn поставлен через apt, а библиотеки — в окружение venv | поставьте gunicorn в окружение: /home/ivan/myapp/venv/bin/pip install gunicorn, и запускайте /home/ivan/myapp/venv/bin/gunicorn; подробнее — No module named |
ModuleNotFoundError: No module named 'app' | gunicorn ищет файл приложения не в той папке | задайте папку проекта: строка WorkingDirectory=/home/ivan/myapp в файле службы или ключ --chdir /home/ivan/myapp |
SyntaxError: … | ошибка в тексте программы | разбор SyntaxError |
IndentationError: …, TabError: … | ошибка в отступах | разбор IndentationError |
ImportError: cannot import name '…' | в модуле нет имени, которое берёт программа | разбор cannot import name |
PermissionError: [Errno 13] Permission denied | пользователю, от которого работает служба, не хватает прав на файл или папку | разбор PermissionError |
Если в журнале Connection in use или Can't connect to, рабочие процессы не запускались вовсе: gunicorn не смог открыть порт. Это разобрано отдельно: Address already in use — порт занят, PermissionError — порт с номером меньше 1024.
Проверьте файл службы
Посмотрите строки WorkingDirectory и ExecStart в файле службы:
systemctl cat myappДля приложения на Flask в файле /home/ivan/myapp/app.py с окружением venv в той же папке строки выглядят так:
WorkingDirectory=/home/ivan/myapp
ExecStart=/home/ivan/myapp/venv/bin/gunicorn --bind 127.0.0.1:8000 app:appДля Django вместо app:app пишут myproject.wsgi, где myproject — папка с файлом wsgi.py, а в WorkingDirectory указывают папку, где лежит manage.py. Если строки WorkingDirectory нет, служба работает из корневой папки /, и gunicorn ищет там файл приложения. После правки файла службы выполните:
sudo systemctl daemon-reload
sudo systemctl restart myappКак устроен файл службы целиком — в разделе Как запустить приложение службой.
Как проверить
Посмотрите состояние службы:
sudo systemctl status myappВ строке Active должно быть active (running). Затем проверьте, что приложение отвечает на своём порту — укажите порт из ключа --bind:
curl -I http://127.0.0.1:8000Если в ответе есть строка с кодом, например HTTP/1.1 200 OK, gunicorn работает. Если сайт за nginx по-прежнему показывает 502, сверьте адрес в его настройках — 502 Bad Gateway. Если приложение запущено как служба systemd, имя службы в примерах — myapp, папка — /home/ivan/myapp. Подставьте свои.
Источники
- Исходный код gunicorn 20.1.0: arbiter.py — строки Booting worker, Exception in worker process, Worker exiting, Shutting down и Reason, причины Worker failed to boot и App failed to load.
- Исходный код gunicorn 25.1.0: arbiter.py — уровень ERROR у строк Shutting down и Reason, повтор текста ошибки.
- Исходный код gunicorn 20.1.0: util.py — как gunicorn ищет приложение: объект application без двоеточия, тексты Failed to find.
- Исходный код gunicorn 20.1.0: glogging.py — вид строки журнала.
- Исходный код gunicorn 20.1.0: config.py — ключи --chdir и --bind; без --chdir gunicorn ищет приложение в текущей папке.
- Исходный код systemd 255: systemd.exec — без WorkingDirectory служба работает из корневой папки.
- Исходный код Django 5.2: шаблон wsgi.py — объект application.
- Исходный код Django 5.2: шаблон проекта — manage.py лежит рядом с папкой, где wsgi.py.
Сверено 22 октября 2026 года.
Что почитать дальше
- Как запустить приложение службой.
- 502 Bad Gatewayесли сайт за nginx не открывается.
- Все ошибки Python и pipтаблица по тексту сообщения.
- Environment= и EnvironmentFile=переменные окружения для приложения.
- User= и WorkingDirectory=папка, из которой запускается приложение.