[BUG] Warn when legend() receives mismatched handles and labels in 2-argument positional form (#31315)

EncryptedDoom · timhoffm · web-flow · commit dfa19f6fe43a · 2026-03-17T14:33:58.000Z
* Implement warning for mismatched legend handles and labels

Add warning for mismatched handles and labels in legend.

* Add regression test for legend argument mismatch

Add regression test for mismatched handles and labels in legend.

* Fix regression test message for legend mismatch

* Fix indentation for test_legend_mismatched_positional_args

* Update lib/matplotlib/legend.py

Co-authored-by: Tim Hoffmann &lt;2836374+timhoffm@users.noreply.github.com&gt;

* Rename test for legend mismatched arguments

* Update lib/matplotlib/tests/test_legend.py

Co-authored-by: Tim Hoffmann &lt;2836374+timhoffm@users.noreply.github.com&gt;

* Implement warning test for legend handle-label mismatch

Added a test to warn on unequal number of handles and labels in legend.

* Add test for legend position argument handling

* Update warning message for legend handle mismatch

* Fix legend creation with list of labels

* gracefully handle generators in mismatch warning

* Update warning message for legend handle mismatch

* Update lib/matplotlib/legend.py

Co-authored-by: Tim Hoffmann &lt;2836374+timhoffm@users.noreply.github.com&gt;

---------

Co-authored-by: Tim Hoffmann &lt;2836374+timhoffm@users.noreply.github.com&gt;
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -1385,6 +1385,11 @@ def _parse_legend_args(axs, *args, handles=None, labels=None, **kwargs):
 
     elif len(args) == 2:  # 2 args: user defined handles and labels.
         handles, labels = args[:2]
+        if (hasattr(handles, "__len__") and hasattr(labels, "__len__")
+                and len(handles) != len(labels)):
+            _api.warn_external(f"Mismatched number of handles and labels: "
+                               f"len(handles) = {len(handles)} "
+                               f"len(labels) = {len(labels)}")
 
     else:
         raise _api.nargs_error('legend', '0-2', len(args))
diff --git a/lib/matplotlib/tests/test_legend.py b/lib/matplotlib/tests/test_legend.py
@@ -292,7 +292,7 @@ def test_hatching():
 def test_legend_remove():
     fig, ax = plt.subplots()
     lines = ax.plot(range(10))
-    leg = fig.legend(lines, "test")
+    leg = fig.legend(lines, ["test"])
     leg.remove()
     assert fig.legends == []
     leg = ax.legend("test")
@@ -424,6 +424,15 @@ def test_parasite(self):
             plt.legend()
         Legend.assert_called_with(host, [p1, p2], ['Density', 'Temperature'])
 
+    def test_legend_warns_on_unequal_number_of_handles_and_labels(self):
+        fig, ax = plt.subplots()
+        line1, = ax.plot([1, 2])
+        line2, = ax.plot([3, 4])
+        with pytest.warns(UserWarning, match="Mismatched number of handles and labels"):
+            ax.legend([line1, line2], ['only_one'])  # 2 handles, 1 label
+        with pytest.warns(UserWarning, match="Mismatched number of handles and labels"):
+            ax.legend([line1], ['label_a', 'label_b'])  # 1 handle, 2 labels
+
 
 class TestLegendFigureFunction:
     # Tests the legend function for figure
