Core: Improve error for null/unknown schema types in table creation (apache#2843)

What changed
- Add a client-side validation error when a PyArrow `null` type is used
with format version < 3, including the field path and a hint to use a
concrete type or format-version 3.
- Add a unit test to verify the clear error message when converting a
PyArrow schema with a null field.

Why
- Prevents misleading REST errors like “Cannot parse type string…
unknown” and points directly to the offending field.

Testing
- make lint
- uv run pytest tests/catalog/test_base.py -k rejects_null_type -v
- make test (timed out at ~42%)

Closes apache#2539

---------

Co-authored-by: Soham <010Soham@users.noreply.github.com>

Author: 010Soham

pyiceberg/io/pyarrow.py

@@ -1435,6 +1435,13 @@ def primitive(self, primitive: pa.DataType) -> PrimitiveType:
         elif pa.types.is_null(primitive):
             # PyArrow null type (pa.null()) is converted to Iceberg UnknownType
             # UnknownType can be promoted to any primitive type in V3+ tables per the Iceberg spec
+            if self._format_version < 3:
+                field_path = ".".join(self._field_names) if self._field_names else "<root>"
+                raise ValueError(
+                    "Null type (pa.null()) is not supported in Iceberg format version "
+                    f"{self._format_version}. Field: {field_path}. "
+                    "Requires format-version=3+ or use a concrete type (string, int, boolean, etc.)."
+                )
             return UnknownType()
         elif isinstance(primitive, pa.UuidType):
             return UUIDType()

tests/catalog/test_base.py

@@ -210,6 +210,16 @@ def test_convert_schema_if_needed(
     assert expected == catalog._convert_schema_if_needed(schema)
 
 
+def test_convert_schema_if_needed_rejects_null_type(catalog: InMemoryCatalog) -> None:
+    schema = pa.schema([pa.field("n1", pa.null())])
+    with pytest.raises(ValueError) as exc_info:
+        catalog._convert_schema_if_needed(schema)
+    message = str(exc_info.value)
+    assert "Null type" in message
+    assert "n1" in message
+    assert "format-version=3" in message
+
+
 def test_create_table_pyarrow_schema(catalog: InMemoryCatalog, pyarrow_schema_simple_without_ids: pa.Schema) -> None:
     catalog.create_namespace(TEST_TABLE_NAMESPACE)
     table = catalog.create_table(