Case-insensitive element-name uniqueness check only works when the existing name is lowercase

[!NOTE]
This whole message is AI-generated. The issue was automatically discovered and reported by an AI agent (Claude) during an autonomous bug hunt on the spatialdata code base. It has not been verified or triaged by a human yet; the needs: triage label is set so that a maintainer can confirm it. The reproduction script below was executed by the agent in an isolated environment (see Environment) and its output is pasted verbatim.

Summary

SpatialData(images={"IMG": a, "img": b}) is accepted (the reverse order is correctly rejected), as is images["Lab"] + labels["lab"]. On APFS, writing the object fails at the second element with ValueError: The Zarr store already exists. Use overwrite=True... because both names resolve to the same directory. check_all_keys_case_insensitively_unique (used by write_element) lowercases both sides and is correct, hence the asymmetry.

Severity (agent's assessment): medium/high — on case-insensitive filesystems (macOS, Windows) write() fails half-way with a misleading error and leaves a partial store

Where: src/spatialdata/_core/validation.py::check_key_is_case_insensitively_unique (compares key.lower() against the raw keys), called from _core/_elements.py::Elements._check_key

Expected behaviour

Both orders (and cross-type collisions) raise the KeyError about case variants.

Reproduction

Save as repro.py and run uv run repro.py (the PEP 723 header pins spatialdata to the commit the bug was found on; replace the URL fragment with @main to test the current main branch).

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "spatialdata @ git+https://github.com/scverse/spatialdata.git@ccf1ea048d054b6624214bf618008a9f9ae223e0",
# ]
# ///
"""The case-insensitive element-name uniqueness check only fires when the existing name is lowercase."""
import os
import shutil
import tempfile
import warnings
import numpy as np
from spatialdata import SpatialData
from spatialdata.models import Image2DModel, Labels2DModel

warnings.simplefilter("ignore")
a = Image2DModel.parse(np.full((1, 4, 4), 1, dtype=np.uint8))
b = Image2DModel.parse(np.full((1, 4, 4), 2, dtype=np.uint8))
bug = False
try:
    sdata = SpatialData(images={"IMG": a, "img": b})
    print("images {'IMG', 'img'}: constructed OK ->", list(sdata.images), "(expected: error, names differ only by case)")
    bug = True
    tmp = tempfile.mkdtemp()
    try:
        sdata.write(os.path.join(tmp, "store.zarr"))
        print("write(): succeeded; on-disk dirs under images/:", sorted(os.listdir(os.path.join(tmp, "store.zarr", "images"))))
    except Exception as e:  # noqa: BLE001
        print("write():", type(e).__name__, str(e)[:110])
    shutil.rmtree(tmp)
except Exception as e:  # noqa: BLE001
    print("images {'IMG', 'img'}:", type(e).__name__, "(correct)")
try:
    SpatialData(images={"img": b, "IMG": a})
    print("images {'img', 'IMG'} (reverse order): constructed OK")
except Exception as e:  # noqa: BLE001
    print("images {'img', 'IMG'} (reverse order):", type(e).__name__, "(correct)")
try:
    SpatialData(images={"Lab": a}, labels={"lab": Labels2DModel.parse(np.zeros((4, 4), dtype=np.uint8))})
    print("images 'Lab' + labels 'lab': constructed OK (expected: error)")
    bug = True
except Exception as e:  # noqa: BLE001
    print("images 'Lab' + labels 'lab':", type(e).__name__, "(correct)")
print("VERDICT:", "BUG REPRODUCED" if bug else "NOT REPRODUCED")

Observed output

images {'IMG', 'img'}: constructed OK -> ['IMG', 'img'] (expected: error, names differ only by case)
write(): ValueError The Zarr store already exists. Use `overwrite=True` to try overwriting the store. Please note that only Zarr s
images {'img', 'IMG'} (reverse order): ValidationError (correct)
images 'Lab' + labels 'lab': constructed OK (expected: error)
VERDICT: BUG REPRODUCED

Possible fix direction (unverified)

if normalized_key in {k.lower() for k in other_keys if k is not None} (or store lowercased keys in _shared_keys). Add tests for both orders and cross-type collisions.

Environment

uv run repro.py with the PEP 723 metadata in the script (fresh, isolated environment; spatialdata built from main @ ccf1ea0 (2026-08-28); Python 3.13, latest releases of the dependencies at run time: pandas 3.0, anndata 0.13, zarr 3.3, dask 2026.8, numpy 2.5, geopandas 1.1, shapely 2.1). macOS (arm64). Also reproduced in a second environment with pandas 2.3.3 / anndata 0.12.11 / numpy 2.4.4 / zarr 3.2.1.

Automatically generated; discovered by an AI agent (Claude) and not yet reviewed by a human.

Start in src/spatialdata/_core/validation.py at check_key_is_case_insensitively_unique, then trace its use through src/spatialdata/_core/_elements.py::_check_key. Run the provided repro.py first. Done means both insertion orders and cross-type case collisions raise the expected KeyError before writing can create a partial store, with regression tests covering these cases.