fix(io): raise helpful error when SLP metadata JSON attribute is missing (#429) (#446)

`read_metadata` previously surfaced a raw h5py `KeyError` ("Can't open
attribute (can't locate attribute: 'json')") when an `.slp` file's
`metadata` group exists but is missing its `json` attribute, giving users
no context or recovery path. This has been seen on user-corrupted files
(talmolab/sleap#2146).

Wrap only the `read_hdf5_attrs` call in `read_metadata` in a `try/except
KeyError` and re-raise a `ValueError(...) from e` that names the file,
explains it is likely corrupt, and gives an h5py recovery snippet. The
decode/`json.loads` lines stay outside the try so a present-but-malformed
blob still surfaces as its own decode error rather than being mislabeled
as corruption. The blanket `except KeyError` also covers a fully-absent
`metadata` group; the "likely corrupt" wording stays accurate for both.
The error propagates automatically through `read_labels` via
`read_skeletons`, so no extra plumbing is added.

Adds four focused tests covering the missing-attribute, missing-group,
read_labels-propagation, and malformed-blob-not-remasked cases.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: talmo

sleap_io/io/slp.py

@@ -1496,8 +1496,28 @@ def read_metadata(labels_path: str, *, _hdf5_file: h5py.File | None = None) -> d
 
     Returns:
         A dict containing the metadata from a SLEAP labels file.
+
+    Raises:
+        ValueError: If the ``metadata`` group is missing its ``json`` attribute
+            (or the group itself is absent), indicating the file is likely
+            corrupt.
     """
-    md = read_hdf5_attrs(labels_path, "metadata", "json", _hdf5_file=_hdf5_file)
+    try:
+        md = read_hdf5_attrs(labels_path, "metadata", "json", _hdf5_file=_hdf5_file)
+    except KeyError as e:
+        raise ValueError(
+            f"The SLEAP labels file {labels_path!r} is missing its required "
+            "metadata JSON blob (the 'metadata' HDF5 group has no readable 'json' "
+            "attribute) and is likely corrupt. If you have a working .slp file "
+            "with the same skeleton, you can copy the attribute into a BACKUP "
+            "COPY of the corrupt file with h5py (back up first):\n"
+            "    import h5py\n"
+            "    with h5py.File('working.slp', 'r') as src, "
+            "h5py.File('corrupt_copy.slp', 'a') as dst:\n"
+            "        dst['metadata'].attrs['json'] = src['metadata'].attrs['json']\n"
+            "Only do this if the skeletons match exactly, otherwise the loaded "
+            "data will be wrong."
+        ) from e
     if isinstance(md, bytes):
         md = md.decode()
     elif isinstance(md, np.ndarray):

tests/io/test_slp.py

@@ -5414,6 +5414,55 @@ def test_read_metadata_ndarray(tmp_path):
     assert result == metadata
 
 
+def test_read_metadata_missing_json_attr_raises_valueerror(tmp_path):
+    """Test read_metadata raises ValueError when 'json' attr is missing."""
+    path = str(tmp_path / "missing_json.slp")
+    with h5py.File(path, "w") as f:
+        grp = f.require_group("metadata")
+        # Group exists but has no 'json' attribute (only an unrelated attr).
+        grp.attrs["format_id"] = 1.1
+
+    with pytest.raises(ValueError, match="missing its required metadata JSON blob"):
+        read_metadata(path)
+
+
+def test_read_labels_missing_json_attr_raises_valueerror(slp_minimal, tmp_path):
+    """Test ValueError propagates to read_labels when 'json' attr is missing."""
+    # Start from a real .slp file so all other datasets are present, then
+    # corrupt a copy by deleting only the 'metadata/json' attribute.
+    path = str(tmp_path / "corrupt.slp")
+    shutil.copy(slp_minimal, path)
+    with h5py.File(path, "a") as f:
+        del f["metadata"].attrs["json"]
+
+    with pytest.raises(ValueError, match="likely corrupt"):
+        read_labels(path)
+
+
+def test_read_metadata_missing_metadata_group_raises_valueerror(tmp_path):
+    """Test read_metadata raises ValueError when 'metadata' group is absent."""
+    path = str(tmp_path / "no_metadata_group.slp")
+    with h5py.File(path, "w") as f:
+        # No 'metadata' group at all.
+        f.require_group("other")
+
+    with pytest.raises(ValueError, match="likely corrupt"):
+        read_metadata(path)
+
+
+def test_read_metadata_malformed_json_not_remasked(tmp_path):
+    """Test malformed (present) JSON surfaces as a decode error, not corruption."""
+    path = str(tmp_path / "malformed_json.slp")
+    with h5py.File(path, "w") as f:
+        grp = f.require_group("metadata")
+        grp.attrs["json"] = b"{not valid json"
+
+    # The corruption message must NOT be raised here; json parsing should fail.
+    with pytest.raises(ValueError) as exc_info:
+        read_metadata(path)
+    assert "missing its required metadata JSON blob" not in str(exc_info.value)
+
+
 def test_read_h5wasm_instances_float64_indices(tmp_path):
     """Test that float64 index values from h5wasm are handled in read_instances."""
     path = str(tmp_path / "instances.h5")