Fixed #19929 -- Improved error when MySQL doesn't have TZ definitions.

Thanks tomas_00 for the report.

2 files changed, 11 insertions, 0 deletions

diff --git a/django/db/models/sql/compiler.py b/django/db/models/sql/compiler.py
index b9d25d98a1..7ddee9785c 100644
--- a/django/db/models/sql/compiler.py
+++ b/django/db/models/sql/compiler.py
@@ -1057,6 +1057,10 @@ class SQLDateTimeCompiler(SQLCompiler):
                 # Datetimes are artifically returned in UTC on databases that
                 # don't support time zone. Restore the zone used in the query.
                 if settings.USE_TZ:
+                    if datetime is None:
+                        raise ValueError("Database returned an invalid value "
+                                         "in QuerySet.dates(). Are time zone "
+                                         "definitions installed?")
                     datetime = datetime.replace(tzinfo=None)
                     datetime = timezone.make_aware(datetime, self.query.tzinfo)
                 yield datetime
diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index 9ab19846f6..9a0f3ca7f8 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -142,6 +142,13 @@ subclass::
     e.g. if all the dates are in one month, it'll show the day-level
     drill-down only.
 
+    .. note::
+
+        ``date_hierarchy`` uses :meth:`QuerySet.datetimes()
+        <django.db.models.query.QuerySet.datetimes>` internally. Please refer
+        to its documentation for some caveats when time zone support is
+        enabled (:setting:`USE_TZ = True <USE_TZ>`).
+
 .. attribute:: ModelAdmin.exclude
 
     This attribute, if given, should be a list of field names to exclude from