django/django · error · CommandError

Required field '%s' specifies a many-to-many relation throug

Error message

Required field '%s' specifies a many-to-many relation through model, which is not supported.

What it means

Raised during createsuperuser.add_arguments() when a field listed in the custom user model's REQUIRED_FIELDS is a many-to-many field whose through model was NOT auto-created by Django. createsuperuser cannot drive membership in an explicit through table from CLI flags, so it refuses to build the argument parser.

Source

Thrown at django/contrib/auth/management/commands/createsuperuser.py:69

                "any other required field. Superusers created with --noinput will "
                "not be able to log in until they're given a valid password."
                % self.UserModel.USERNAME_FIELD
            ),
        )
        parser.add_argument(
            "--database",
            default=DEFAULT_DB_ALIAS,
            choices=tuple(connections),
            help='Specifies the database to use. Default is "default".',
        )
        for field_name in self.UserModel.REQUIRED_FIELDS:
            field = self.UserModel._meta.get_field(field_name)
            if field.many_to_many:
                if (
                    field.remote_field.through
                    and not field.remote_field.through._meta.auto_created
                ):
                    raise CommandError(
                        "Required field '%s' specifies a many-to-many "
                        "relation through model, which is not supported." % field_name
                    )
                else:
                    parser.add_argument(
                        "--%s" % field_name,
                        action="append",
                        help=(
                            "Specifies the %s for the superuser. Can be used "
                            "multiple times." % field_name,
                        ),
                    )
            else:
                parser.add_argument(
                    "--%s" % field_name,
                    help="Specifies the %s for the superuser." % field_name,
                )

View on GitHub (pinned to ae25a40be0)

Solutions

1. Remove the M2M-with-through field from your user model's REQUIRED_FIELDS (REQUIRED_FIELDS should only name fields needed to create a minimal superuser).
2. If the relation must be populated, assign it after creation via the shell/admin rather than via createsuperuser flags.
3. Alternatively, use an auto-created M2M (no explicit through) if you truly need it as a CLI flag.

Example fix

// before:
class CustomUser(AbstractBaseUser):
    groups = models.ManyToManyField(Group, through=Membership)
    REQUIRED_FIELDS = ['groups']  # raises on createsuperuser

// after:
class CustomUser(AbstractBaseUser):
    groups = models.ManyToManyField(Group, through=Membership)
    REQUIRED_FIELDS = ['email']  # only plain required fields

from django.contrib.auth import get_user_model
UserModel = get_user_model()
for name in UserModel.REQUIRED_FIELDS:
    f = UserModel._meta.get_field(name)
    if f.many_to_many and f.remote_field.through and not f.remote_field.through._meta.auto_created:
        raise SystemExit(
            f'REQUIRED_FIELDS contains M2M-with-through {name!r}; remove it before running createsuperuser'
        )

When it happens

Trigger: Defining a custom user model (AUTH_USER_MODEL) with a REQUIRED_FIELDS entry that is a ManyToManyField(using an explicit `through=Membership` model), then running `manage.py createsuperuser`.

Common situations: Adding a roles/groups-style M2M with a custom through model to a custom user and accidentally listing it in REQUIRED_FIELDS; refactoring a user model and forgetting that REQUIRED_FIELDS should only contain simple required columns.

Related errors

• %s cannot be blank.
• You must use --%s with --noinput.
• The app label '%s' is not a valid Python identifier.
• The app module %r has multiple filesystem locations (%r); yo
• The app module %r has no filesystem location, you must confi

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