Improve JSON encoding error message

python/CHANGELOG.rst

@@ -31,6 +31,9 @@
   ``TableCollection.sort`` no longer sorts individuals.
   (:user:`benjeffery`, :issue:`1774`, :pr:`1789`)
 
+- Metadata encoding errors now raise ``MetadataEncodingError``
+  (:user:`benjeffery`, :issue:`1505`, :pr:`1827`).
+
 **Features**
 
 - Add ``TableCollection.sort_individuals`` to sort the individuals as this is no longer done by the

python/tests/test_metadata.py

@@ -566,6 +566,14 @@ def test_nested_default_error(self):
         ):
             tskit.MetadataSchema(schema)
 
+    def test_bad_type_error(self):
+        ms = tskit.MetadataSchema({"codec": "json"})
+        with pytest.raises(
+            exceptions.MetadataEncodingError,
+            match="Could not encode metadata of type TableCollection",
+        ):
+            ms.validate_and_encode_row(tskit.TableCollection(1))
+
 
 class TestStructCodec:
     def encode_decode(self, method_name, sub_schema, obj, buffer):

python/tskit/exceptions.py

@@ -54,3 +54,9 @@ class MetadataSchemaValidationError(TskitException):
     """
     A metadata schema object did not validate against the metaschema.
     """
+
+
+class MetadataEncodingError(TskitException):
+    """
+    A metadata object was of a type that could not be encoded
+    """

python/tskit/metadata.py

@@ -144,7 +144,12 @@ def __init__(self, schema: Mapping[str, Any]) -> None:
         }
 
     def encode(self, obj: Any) -> bytes:
-        return tskit.canonical_json(obj).encode()
+        try:
+            return tskit.canonical_json(obj).encode()
+        except TypeError as e:
+            raise exceptions.MetadataEncodingError(
+                f"Could not encode metadata of type {str(e).split()[3]}"
+            )
 
     def decode(self, encoded: bytes) -> Any:
         result = json.loads(encoded.decode())