django/django · critical · ImproperlyConfigured

AUTH_USER_MODEL refers to model '%' that has not been instal

Error message

AUTH_USER_MODEL refers to model '%' that has not been installed

What it means

Raised as ImproperlyConfigured by get_user_model() when the label.model parses but the model cannot be found, i.e. apps.get_model() raises LookupError. This means the referenced app/model is not installed or does not define that model.

Source

Thrown at django/contrib/auth/__init__.py:272

            user = None
    await user_logged_out.asend(sender=user.__class__, request=request, user=user)
    await request.session.aflush()

    _set_auth_user(request)


def get_user_model():
    """
    Return the User model that is active in this project.
    """
    try:
        return django_apps.get_model(settings.AUTH_USER_MODEL, require_ready=False)
    except ValueError:
        raise ImproperlyConfigured(
            "AUTH_USER_MODEL must be of the form 'app_label.model_name'"
        )
    except LookupError:
        raise ImproperlyConfigured(
            "AUTH_USER_MODEL refers to model '%s' that has not been installed"
            % settings.AUTH_USER_MODEL
        )


def get_user(request):
    """
    Return the user model instance associated with the given request session.
    If no user is retrieved, return an instance of `AnonymousUser`.
    """
    from .models import AnonymousUser

    user = None
    try:
        user_id = _get_user_session_key(request)
        backend_path = request.session[BACKEND_SESSION_KEY]
    except KeyError:
        pass

View on GitHub (pinned to ae25a40be0)

Solutions

1. Add the app containing the custom User model to INSTALLED_APPS (before django.contrib.auth when swapping mid-project).
2. Correct the app_label/model_name spelling to match the installed app and model class.
3. Ensure migrations for the custom user app exist and run first; follow the custom-user migration docs if swapping in an existing project.

Example fix

// before: app not installed
AUTH_USER_MODEL = "accounts.User"
# INSTALLED_APPS lacks "accounts"

// after: install the app
INSTALLED_APPS = [..., "accounts", "django.contrib.auth", ...]
AUTH_USER_MODEL = "accounts.User"

# Confirm the app and model resolve before the first request.
from django.apps import apps
from django.conf import settings

def validate_user_model():
    app_label, model_name = settings.AUTH_USER_MODEL.split('.')
    if app_label not in {c.label for c in apps.get_app_configs()}:
        raise ImproperlyConfigured(f'App {app_label!r} not in INSTALLED_APPS')
    cfg = apps.get_app_config(app_label)
    if not cfg.models:
        apps.get_model(app_label, model_name)  # raises LookupError if missing

When it happens

Trigger: AUTH_USER_MODEL = 'accounts.User' but 'accounts' is not in INSTALLED_APPS, or the User model was renamed/removed. Fires at the first get_user_model() call (auth imports, migrations, admin loading).

Common situations: Swapping to a custom user model in an app that is not yet in INSTALLED_APPS; typos in app_label or model name; migrations run before the custom user app is installed; circular import causing the app not to be ready.

Related errors

• AUTH_USER_MODEL must be of the form 'app_label.model_name'
• No authentication backends have been defined. Does AUTHENTIC
• Deprecated email settings are not allowed when MAILERS is de
• Requested %s, but settings are not configured. You must eith
• The SECRET_KEY setting must not be empty.

AI-assisted analysis of django/django@ae25a40be0 (2026-08-06). Data as JSON: /api/errors/c6b2baebb9f626ac. Report an issue: GitHub.