diff --git a/docs/source/common_issues.rst b/docs/source/common_issues.rst
index 42962581702f..465035307d5d 100644
--- a/docs/source/common_issues.rst
+++ b/docs/source/common_issues.rst
@@ -188,6 +188,8 @@ Ignoring a whole file
 
 A ``# type: ignore`` comment at the top of a module (before any statements,
 including imports or docstrings) has the effect of ignoring the entire contents of the module.
+This behaviour can be surprising and result in
+"Module ... has no attribute ... [attr-defined]" errors.
 
 To only ignore errors, use a top-level ``# mypy: ignore-errors`` comment instead.
 To only ignore errors with a specific error code, use a top-level