lincolnloop · maribedran · Oct 8, 2025
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -36,6 +36,11 @@ WIP (9.0)
     StyledPilImage(embeded_image=..., embeded_image_path=...)  # Old
     StyledPilImage(embedded_image=..., embedded_image_path=...)  # New

+- Use warning instead of raising ValueError when an embedded image is provided
+  with a low error correction level. With a low error correction and an
+  embedded image, the QR code might become unreadable, but not necessarily.
+
+
 WIP 8.x
 -------


diff --git a/qrcode/main.py b/qrcode/main.py
@@ -1,6 +1,7 @@
 from __future__ import annotations

 import sys
+import warnings
 from bisect import bisect_left
 from typing import Generic, Literal, NamedTuple, Optional, TypeVar, cast, overload

@@ -337,8 +338,9 @@ def make_image(self, image_factory=None, **kwargs):
        if (
            kwargs.get("embedded_image_path") or kwargs.get("embedded_image")
        ) and self.error_correction != constants.ERROR_CORRECT_H:
-            raise ValueError(
-                "Error correction level must be ERROR_CORRECT_H if an embedded image is provided"
+            warnings.warn(
+                "Low error correction level with an embedded image might lead to unreadable QR codes. "
+                "Use ERROR_CORRECT_H for better results.",
            )

        _check_box_size(self.box_size)

diff --git a/qrcode/tests/test_qrcode_pil.py b/qrcode/tests/test_qrcode_pil.py
@@ -121,30 +121,36 @@ def test_render_styled_with_mask(mask):


 def test_embedded_image_and_error_correction(tmp_path):
-    "If an embedded image is specified, error correction must be the highest so the QR code is readable"
+    "If an embedded image is specified, error correction should be the highest so the QR code is readable"
    tmpfile = str(tmp_path / "test.png")
    embedded_img = Image.new("RGB", (10, 10), color="red")
    embedded_img.save(tmpfile)

    qr = qrcode.QRCode(error_correction=qrcode.ERROR_CORRECT_L)
    qr.add_data(UNICODE_TEXT)
-    with pytest.raises(ValueError):
+
+    message = (
+        "Low error correction level with an embedded image might lead to unreadable QR codes. "
+        "Use ERROR_CORRECT_H for better results."
+    )
+
+    with pytest.warns(match=message):
        qr.make_image(embedded_image_path=tmpfile)
-    with pytest.raises(ValueError):
+    with pytest.warns(match=message):
        qr.make_image(embedded_image=embedded_img)

    qr = qrcode.QRCode(error_correction=qrcode.ERROR_CORRECT_M)
    qr.add_data(UNICODE_TEXT)
-    with pytest.raises(ValueError):
+    with pytest.warns(match=message):
        qr.make_image(embedded_image_path=tmpfile)
-    with pytest.raises(ValueError):
+    with pytest.warns(match=message):
        qr.make_image(embedded_image=embedded_img)

    qr = qrcode.QRCode(error_correction=qrcode.ERROR_CORRECT_Q)
    qr.add_data(UNICODE_TEXT)
-    with pytest.raises(ValueError):
+    with pytest.warns(match=message):
        qr.make_image(embedded_image_path=tmpfile)
-    with pytest.raises(ValueError):
+    with pytest.warns(match=message):
        qr.make_image(embedded_image=embedded_img)

    # The only accepted correction level when an embedded image is provided