Troubleshooting¶

Startup Issues¶

ImportError: No module named ‘gunicorn’¶

Install the backend:

pip install django-prodserver[gunicorn]  # or uvicorn, celery, etc.

PRODUCTION_PROCESSES not found¶

Add to settings.py:

PRODUCTION_PROCESSES = {
    "web": {
        "BACKEND": "django_prodserver.backends.servers.gunicorn.GunicornServer",
        "ARGS": {"bind": "0.0.0.0:8000"},
    }
}

Process name not found¶

Ensure the process name matches your config:

# If configured as "web":
python manage.py server web

Port Issues¶

Port already in use¶

# Find and stop the process
lsof -i :8000
kill <PID>

# Or use a different port
"ARGS": {"bind": "0.0.0.0:8001"}

Permission denied on port 80/443¶

Use a higher port with a reverse proxy, or:

# Linux only
sudo setcap 'cap_net_bind_service=+ep' /path/to/python

Backend Issues¶

Gunicorn: Worker timeout¶

Increase timeout:

"ARGS": {"timeout": "120"}

Uvicorn: ASGI app not found¶

Ensure asgi.py exists:

# myproject/asgi.py
from django.core.asgi import get_asgi_application
application = get_asgi_application()

Celery: Broker connection failed¶

# Verify Redis is running
redis-cli ping

# Check CELERY_BROKER_URL
CELERY_BROKER_URL = 'redis://localhost:6379/0'

Celery: Tasks not discovered¶

# myproject/celery.py
app.autodiscover_tasks()

# myproject/__init__.py
from .celery import app as celery_app
__all__ = ('celery_app',)

Performance Issues¶

High memory usage¶

Reduce workers and enable recycling:

# Gunicorn
"ARGS": {"workers": "2", "max-requests": "1000"}

# Celery
"ARGS": {"max-tasks-per-child": "1000"}

Slow response times¶

Increase workers/concurrency
Check database query performance
Add caching

Database Issues¶

Too many connections¶

DATABASES = {
    'default': {
        'CONN_MAX_AGE': 600,  # Reuse connections
    }
}

And reduce worker count.

Docker Issues¶

Container exits immediately¶

Check logs:

docker logs container_name

Use health checks and wait for dependencies.

Can’t connect to database¶

Use service name as host:

DATABASES = {'default': {'HOST': 'db'}}  # Not 'localhost'

Debugging¶

# Check installation
pip show django-prodserver

# Validate config
python manage.py check

# Verbose output
python manage.py server web --verbosity 3

# Check processes
ps aux | grep python
lsof -i :8000

Getting Help¶

Search existing issues
Include: Django version, django-prodserver version, backend, full error, config