Raise clear error when non-StreamBlock is passed as top-level block in StreamField (#13068)

Fixes #13067

CHANGELOG.txt

@@ -24,6 +24,7 @@ Changelog
  * Preserve query parameters when redirecting from the API `find` view to the `detail` view (Andrew Hosgood)
  * Add 'Edit' button to success message after copying page (Dhruvi Patel)
  * Restrict file dialog in multiple image uploader to the allowed image file types (mubarak-mustopha)
+ * Raise clear error when non-StreamBlock is used as top-level block in StreamField (Clifford Gama)
  * Fix: Handle lazy translation strings as `preview_value` for `RichTextBlock` (Seb Corbin)
  * Fix: Fix handling of newline-separated choices in form builder when using non-windows newline characters (Baptiste Mispelon)
  * Fix: Ensure `WAGTAILADMIN_LOGIN_URL` is respected when logging out of the admin (Antoine Rodriguez, Ramon de Jezus)

docs/releases/7.1.md

@@ -36,6 +36,7 @@ The [](settings) app now allows permission over site settings to be granted on a
  * Preserve query parameters when redirecting from the API `find` view to the `detail` view (Andrew Hosgood)
  * Add 'Edit' button to success message after copying page (Dhruvi Patel)
  * Restrict file dialog in multiple image uploader to the allowed image file types (mubarak-mustopha)
+ * Raise clear error when non-StreamBlock is used as top-level block in StreamField (Clifford Gama)
 
 ### Bug fixes
 

wagtail/fields.py

@@ -146,6 +146,13 @@ class StreamField(models.Field):
 
             block = StreamBlock(child_blocks)
 
+        if not isinstance(block, StreamBlock):
+            raise TypeError(
+                f"The top-level block must be a StreamBlock (got {type(block).__name__}). "
+                "Either pass a StreamBlock instance/class, or a list of block definitions "
+                "as (name, block) tuples."
+            )
+
         block.set_meta_options(self.block_opts)
         return block
 

wagtail/tests/test_streamfield.py

@@ -1200,3 +1200,17 @@ class TestDeconstructStreamFieldWithLookup(TestCase):
                 },
             },
         )
+
+
+class TestBlockTypeValidation(TestCase):
+    def test_non_streamblock_raises_correct_error(self):
+        """stream_block raises useful error message when non-StreamBlock is provided."""
+        msg = (
+            "The top-level block must be a StreamBlock (got StructBlock). "
+            "Either pass a StreamBlock instance/class, or a list of block definitions "
+            "as (name, block) tuples."
+        )
+
+        with self.assertRaisesMessage(TypeError, msg):
+            field = StreamField(blocks.StructBlock([("name", blocks.CharBlock())]))
+            field.stream_block