[1.7.x] Fixed #22874: Document that AUTH_USER_MODEL must be in first migration

2 files changed, 11 insertions, 1 deletions

diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 6ea6c2c113..0c6e4fc5af 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -2435,7 +2435,9 @@ The model to use to represent a User. See :ref:`auth-custom-user`.
 .. warning::
     You cannot change the AUTH_USER_MODEL setting during the lifetime of
     a project (i.e. once you have made and migrated models that depend on it)
-    without serious effort. It is intended to be set at the project start.
+    without serious effort. It is intended to be set at the project start,
+    and the model it refers to must be available in the first migration of
+    the app that it lives in.
     See :ref:`auth-custom-user` for more details.
 
 .. setting:: LOGIN_REDIRECT_URL
diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt
index 610de93d01..e84fb2b8fe 100644
--- a/docs/topics/auth/customizing.txt
+++ b/docs/topics/auth/customizing.txt
@@ -386,6 +386,14 @@ use as your User model.
    fix your schema, port your data from the old user table, and possibly
    manually reapply some migrations.
 
+.. warning::
+
+   Due to limitations of Django's dynamic dependency feature for swappable
+   models, you must ensure that the model referenced by :setting:`AUTH_USER_MODEL`
+   is created in the first migration of its app (usually called ``0001_initial``);
+   otherwise, you will have dependency issues.
+
+
 Referencing the User model
 --------------------------