Mention common resolutions for build errors (#12154)

Might help with breaking changes that result from #9636

Co-authored-by: hauntsaninja <>

mypy/build.py

@@ -2830,8 +2830,15 @@ def load_graph(sources: List[BuildSource], manager: BuildManager,
  )
  manager.errors.report(
  -1, -1,
- "Are you missing an __init__.py? Alternatively, consider using --exclude to "
- "avoid checking one of them.",
+ "See https://mypy.readthedocs.io/en/stable/running_mypy.html#mapping-file-paths-to-modules " # noqa: E501
+ "for more info",
+ severity='note',
+ )
+ manager.errors.report(
+ -1, -1,
+ "Common resolutions include: a) using `--exclude` to avoid checking one of them, "
+ "b) adding `__init__.py` somewhere, c) using `--explicit-package-bases` or "
+ "adjusting MYPYPATH",
  severity='note'
  )
 
@@ -2905,6 +2912,12 @@ def load_graph(sources: List[BuildSource], manager: BuildManager,
  "for more info",
  severity='note',
  )
+ manager.errors.report(
+ -1, 0,
+ "Common resolutions include: a) adding `__init__.py` somewhere, "
+ "b) using `--explicit-package-bases` or adjusting MYPYPATH",
+ severity='note',
+ )
  manager.errors.raise_error()
 
  seen_files[newst_path] = newst

test-data/unit/cmdline.test

@@ -59,7 +59,8 @@ undef
 undef
 [out]
 dir/a.py: error: Duplicate module named "a" (also at "dir/subdir/a.py")
-dir/a.py: note: Are you missing an __init__.py? Alternatively, consider using --exclude to avoid checking one of them.
+dir/a.py: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#mapping-file-paths-to-modules for more info
+dir/a.py: note: Common resolutions include: a) using `--exclude` to avoid checking one of them, b) adding `__init__.py` somewhere, c) using `--explicit-package-bases` or adjusting MYPYPATH
 == Return code: 2
 
 [case testCmdlineNonPackageSlash]
@@ -125,7 +126,8 @@ mypy: can't decode file 'a.py': unknown encoding: uft-8
 # type: ignore
 [out]
 two/mod/__init__.py: error: Duplicate module named "mod" (also at "one/mod/__init__.py")
-two/mod/__init__.py: note: Are you missing an __init__.py? Alternatively, consider using --exclude to avoid checking one of them.
+two/mod/__init__.py: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#mapping-file-paths-to-modules for more info
+two/mod/__init__.py: note: Common resolutions include: a) using `--exclude` to avoid checking one of them, b) adding `__init__.py` somewhere, c) using `--explicit-package-bases` or adjusting MYPYPATH
 == Return code: 2
 
 [case testFlagsFile]
@@ -1144,6 +1146,7 @@ import foo.bar
 [out]
 src/foo/bar.py: error: Source file found twice under different module names: "src.foo.bar" and "foo.bar"
 src/foo/bar.py: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#mapping-file-paths-to-modules for more info
+src/foo/bar.py: note: Common resolutions include: a) adding `__init__.py` somewhere, b) using `--explicit-package-bases` or adjusting MYPYPATH
 == Return code: 2
 
 [case testEnableInvalidErrorCode]