Daphne - ASGI Server

Common errors

• ModuleNotFoundError: No module named 'daphne'

  cause Daphne is either not installed in the current Python environment, or the Python interpreter running the application cannot find the installed `daphne` package. This often happens in virtual environments or Docker containers if the installation command was not run correctly or the environment is not activated.
  fix Ensure Daphne is installed in the correct environment by running `pip install daphne` or, if using Django Channels, `python -m pip install -U 'channels[daphne]'`.

• CRITICAL Listen failure: Couldn't listen on 0.0.0.0:8001 Address already in use

  cause Another process is already using the port that Daphne is trying to bind to (e.g., port 8001). This can be a previous instance of Daphne, another web server, or any other application listening on that port.
  fix Either stop the process currently using the port (e.g., using `sudo lsof -i :8001` to find and `kill` it) or configure Daphne to listen on a different, available port using the `-p` flag, for example: `daphne -p 8002 your_project.asgi:application`.

• ValueError: No Application Configured for Scope Type 'websocket'

  cause Daphne received a WebSocket connection request, but the ASGI application's `ProtocolTypeRouter` is not correctly configured to handle 'websocket' scope types or the routing for websockets is missing or incorrect in `asgi.py`.
  fix Ensure your `asgi.py` file correctly defines a `ProtocolTypeRouter` that includes a 'websocket' key pointing to an `AuthMiddlewareStack` and a `URLRouter` that routes your WebSocket consumers. For example: `application = ProtocolTypeRouter({ "http": get_asgi_application(), "websocket": AuthMiddlewareStack(URLRouter(your_app.routing.websocket_urlpatterns)), })`.

• ImproperlyConfigured: Requested setting INSTALLED_APPS, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.

  cause This error occurs when Django's settings haven't been loaded before parts of your application (often related to Channels or Daphne setup) try to access them. This is typically a problem with the order of imports or environment variable setup in your `asgi.py` file or similar entry point.
  fix In your `asgi.py` file, ensure `os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'your_project_name.settings')` and `django.setup()` are called before any Django models or settings-dependent code is imported or accessed.

• AttributeError: module 'your_project_name.asgi' has no attribute 'application'

  cause Daphne is trying to find an ASGI application object named `application` within the specified module (e.g., `your_project_name.asgi`), but it cannot find it. This usually means the `application` variable is not defined or is misspelled in your `asgi.py` file.
  fix Verify that your `asgi.py` file explicitly defines a variable named `application` that holds your ASGI application instance, typically an instance of `ProtocolTypeRouter`. For example: `application = ProtocolTypeRouter(...)`. Ensure the casing is correct.

Warnings

• gotcha Daphne requires Python 3.9 or later. Using older Python versions will lead to installation or runtime errors.
  Fix: Ensure your environment uses Python 3.9 or a newer compatible version.
• gotcha When `daphne` is added to `INSTALLED_APPS` for `runserver` integration, it can conflict with other third-party apps that also overload or replace the `runserver` command (e.g., Whitenoise's `runserver_nostatic`).
  Fix: Place `daphne` at the very beginning of your `INSTALLED_APPS` list in your Django settings to give it precedence.
• gotcha Daphne's HTTP/2 support is limited to 'normal' requests and does not include extended features like Server Push. If using a reverse proxy in front of Daphne for HTTP/2, ensure the proxy correctly understands and passes through the HTTP/2 connection.
  Fix: Be aware of the limitations for HTTP/2 features. Configure your reverse proxy to correctly handle HTTP/2 passthrough if you intend to use it with Daphne.
• gotcha Setting a root path (equivalent to WSGI's `SCRIPT_NAME`) can be done via the `Daphne-Root-Path` HTTP header or the `--root-path` command-line option. The header takes precedence. The root path value should start with a slash but not end with one.
  Fix: Use either the `Daphne-Root-Path` header or `--root-path` option, ensuring the format is `/your_path` (e.g., `/forum`, not `/forum/`).

Install

• pip install daphne Install Daphne

Quickstart

Daphne is typically run from the command line, pointing it to your ASGI application. For a Django project, this involves creating or modifying the `asgi.py` file to define your ASGI application, then invoking Daphne as shown below. The example `asgi.py` demonstrates a basic setup for a Django project without WebSockets.

# myproject/asgi.py
import os
from channels.routing import ProtocolTypeRouter
from django.core.asgi import get_asgi_application

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')

# Initialize Django ASGI application early to ensure the AppRegistry
# is populated before importing code that may import ORM models.
django_asgi_app = get_asgi_application()

application = ProtocolTypeRouter({
    "http": django_asgi_app,
    # Add WebSocket protocol here if using Django Channels
    # "websocket": URLRouter(websocket_urlpatterns)
})

# To run:
# Ensure myproject is on the Python path (e.g., run from parent directory of myproject)
# daphne -b 0.0.0.0 -p 8000 myproject.asgi:application