# Gunicorn "Worker failed to boot": what it means and how to fix it

> Gunicorn's worker could not load your application, so the master process shut down. The cause is the Python traceback printed just above the message: most often a missing package or variable, or a wrong module:variable path in the gunicorn command. Fix what the traceback names and the workers boot.

Source: https://livops.dev/en/guides/error-gunicorn-worker-failed-to-boot

By Livops team, the people who build and run Livops. Updated 19 November 2026.

The end of a failed start looks like this:

```text
[INFO] Booting worker with pid: 7
Traceback (most recent call last):
  ...
ModuleNotFoundError: No module named 'myproject'
[INFO] Worker exiting (pid: 7)
[ERROR] Worker (pid:7) exited with code 3
[ERROR] Shutting down: Master
[ERROR] Reason: Worker failed to boot.
```

This page explains what Gunicorn is reporting, lists the causes from the most common, shows how to reproduce the boot on your machine, and says what Livops does when a Gunicorn app does not start.

## What does the error mean?

Gunicorn starts a master process, which forks workers. Each worker imports the application you named as `MODULE_NAME:VARIABLE_NAME`[1]. If that import raises, the worker exits with a boot error, and the master shuts down rather than restart workers that will fail the same way.

So "Worker failed to boot" is never the cause. The cause is the exception the worker printed just before it, and that is what you fix.

## Causes, most common first

### 1. An exception while importing your app

The traceback ends in one of these:

- `ModuleNotFoundError: No module named 'flask'` — a package is not installed where Gunicorn runs. See [ModuleNotFoundError after a deploy](https://livops.dev/en/guides/error-module-not-found-python).
- `KeyError: 'SECRET_KEY'` or Django's `ImproperlyConfigured` — a variable the settings read at import is not set on the server.
- `OperationalError` or `Connection refused` — the code connects to a database at import, and the database is not there yet.

Set the variable, add the package, or move the connection out of import time.

### 2. The app path in the command is wrong

The argument must be the module and the variable: `module:variable`, where the module can be a dotted path[1]. Typical mistakes and fixes:

```sh
gunicorn app:app                           # app.py with app = Flask(__name__)
gunicorn "app:create_app()"                # an application factory, quoted
gunicorn myproject.wsgi:application        # Django: the folder that holds wsgi.py
gunicorn --chdir src main:app              # code under src/
```

`--chdir` changes to that directory before the app is loaded[2]. Without it, Gunicorn imports from where it is started. When the module imports but the variable is wrong, the message changes to `Failed to find attribute 'app' in 'main'` and `Reason: App failed to load.`

### 3. Gunicorn runs outside your virtual environment

A system `gunicorn` cannot import packages installed in `.venv`. Start the one inside it:

```sh
.venv/bin/gunicorn app:app
# or
.venv/bin/python -m gunicorn app:app
```

### 4. Workers are killed for memory

If workers vanish without a traceback, check for `SIGKILL`; in a container with a memory limit the usual culprit is the out-of-memory killer[3]. Each worker holds a copy of the app. Use fewer workers (`--workers 2`), or `--preload`, which loads the app before forking and can save RAM[2].

### 5. A slow boot hits the timeout

The related message is `WORKER TIMEOUT`. Workers silent for longer than `--timeout`, 30 seconds by default, are killed and restarted[2]. Loading a large model or warming a cache at import can take longer. Load it lazily, or raise the timeout for that app.

## How to confirm the fix locally

Start Gunicorn the way the server does, with one worker and the same variables, and watch it load:

```sh
export SECRET_KEY=dev DATABASE_URL=postgres://...
.venv/bin/python -c "import myproject.wsgi"      # the import alone
.venv/bin/gunicorn --workers 1 --preload --bind 127.0.0.1:8000 myproject.wsgi:application
curl -i http://127.0.0.1:8000/
```

The `python -c` line raises exactly the exception the worker would. `gunicorn --check-config` checks the configuration and exits with 0 when it is correct and 1 when it is not[2], which is a quick test for a config file.

## On Livops

- **The command is written for you when it can be.** For Django with `gunicorn` in its requirements, the start command is `.venv/bin/gunicorn <project>.wsgi:application --bind 0.0.0.0:3000`; for Flask with Gunicorn, `.venv/bin/gunicorn <module>:<app> --bind 0.0.0.0:<port>`. A bare `gunicorn` in your `Procfile` is pointed at the project's `.venv`. Django also gets `migrate` before every start.
- **PORT is set.** When `PORT` is defined, Gunicorn's default bind is `0.0.0.0:$PORT`[2], and Livops always defines it for a web service.
- **The cause is in the deploy's log.** If the app does not answer within a minute, the deploy fails as `start_failed` and the log shows the app's last lines, with the error line kept even when a long traceback pushed it out of the tail. When that line is a missing module or a missing variable, a **Tip:** line under it says what to add. The previous version keeps running.
- **Memory is a setting.** Each service has a memory tier: its type's default, 512, 1024 or 2048 MiB. When the service is stopped for using more, the log says so, and the assistant can propose the next tier as a card. Nothing changes until you press it.
- **The assistant explains.** The button next to a failed deploy reads the log and says what to fix.

More on failed starts: [The app did not start](https://livops.dev/en/docs/error-start).

## Questions

**Where is the real error?**

Above the Worker failed to boot line, in the traceback the worker printed before it exited. Its last line, such as ModuleNotFoundError or KeyError, is the cause. Gunicorn's own lines only report that the worker died.

**What is the difference between Worker failed to boot and App failed to load?**

Worker failed to boot (exit code 3) means importing your code raised an exception. App failed to load (exit code 4) means Gunicorn imported the module but could not find the application in it, as in Failed to find attribute 'app' in 'main'. The second is almost always a wrong module:variable in the command.

**How do I get a shorter, clearer error?**

Run gunicorn with --workers 1 --preload. The app is loaded once in the master, so the traceback is printed once instead of once per worker.

**My workers die with no traceback at all. Is it the same problem?**

No. A worker that disappears without a log was usually killed with SIGKILL, often by the out-of-memory killer in a container. Use fewer workers, preload the app, or give the service more memory.

**Do I need --bind on Livops?**

No. When the PORT variable is set, Gunicorn binds to 0.0.0.0 on that port by default, and Livops sets PORT. The start commands Livops writes for Django and Flask still give --bind 0.0.0.0 explicitly.

## Sources

1. [Gunicorn — Running Gunicorn](https://gunicorn.org/run/). Checked 19 November 2026.
2. [Gunicorn — Settings](https://gunicorn.org/reference/settings/). Checked 19 November 2026.
3. [Gunicorn — FAQ](https://gunicorn.org/faq/). Checked 19 November 2026.
