gunicorn/uvicorn "Worker failed to boot" - App Import Errors in CI

gunicorn/uvicorn could not start a worker because importing your application object failed. Either the module:app target is wrong, the app raises at import time, or a missing dependency/env var crashes the import.

What this error means

Starting the server in CI (an integration test or smoke check) fails with "Worker failed to boot" / "Error loading ASGI app" and an arbiter that gives up after the workers exit immediately. No requests are ever served.

gunicorn output

[ERROR] Exception in worker process
ModuleNotFoundError: No module named 'app.main'
[ERROR] Worker (pid:14) exited with code 3
[ERROR] Shutting down: Master
[ERROR] Reason: Worker failed to boot.

Common causes

Wrong application target

The module:callable path (app.main:app, myproj.wsgi:application) doesn’t match the actual module or object name, so import resolution fails before the server starts.

App raises at import time

The app object executes code at import (connecting to a DB, reading a required env var). If that env/service is absent in CI, the import throws and the worker can’t boot.

How to fix it

Import the app target directly first

Reproduce the boot failure without the server to see the real traceback.

Terminal

python -c "from app.main import app; print(app)"
# then start with the verified target
gunicorn -k uvicorn.workers.UvicornWorker app.main:app

Provide required env/services in CI

Set every env var the app reads at import (DB URL, secrets) in the CI job.
Defer connections to startup events/lazy init instead of module import where possible.
Use the correct worker class (uvicorn.workers.UvicornWorker for ASGI apps under gunicorn).

How to prevent it

Keep the module:app target correct and tested with a direct import.
Avoid side effects (DB connects, mandatory env reads) at import time.
Provide all required environment in CI before booting the server.