`layers` can be 3D on-disk

[ilan-gold]

Please make sure these conditions are met

• I have checked that this issue has not already been reported.
• I have confirmed this bug exists on the latest version of anndata.
• (optional) I have confirmed this bug exists on the main branch of anndata.

Report

Code:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "anndata@git+https://github.com/scverse/anndata.git",
# ]
# ///

import anndata as ad
import numpy as np
adata = ad.AnnData(layers={"foo": np.arange(27).reshape((3, 3, 3))})
adata.write_h5ad("foo.h5ad")

Traceback:

No traceback but this is a violation of our spec: https://anndata.readthedocs.io/en/latest/fileformat-prose.html#anndata-specification-v0-1-0

cc @Zethson @eroell This is a pretty big deal that you guys are now relying on this. When I heard that you were doing this, I assumed implicitly that it was checked and kosher, but @eroell approached me about something which prompted me to check this.

Versions

anndata 0.12.14.dev1+g5d5858d89.d20260508
numpy 2.4.4

---

xarray 2026.2.0
packaging 26.0
h5py 3.16.0
cloudpickle 3.1.2
pytz 2026.2
MarkupSafe 3.0.3
charset-normalizer 3.4.4
google-crc32c 1.8.0
pandas 2.3.3
PyYAML 6.0.3
legacy-api-wrap 1.5
python-dateutil 2.9.0.post0
pyarrow 23.0.1
donfig 0.8.1.post1
scipy 1.17.1
scverse-misc 0.0.3
msgpack 1.1.2
typing_extensions 4.15.0
psutil 7.2.2
dask 2026.1.2
tblib 3.2.2
numcodecs 0.16.5
session-info2 0.4
natsort 8.4.0
threadpoolctl 3.6.0
scanpy 1.12
awkward 2.9.0
fast-array-utils 1.3.1
Jinja2 3.1.6
awkward_cpp 52
six 1.17.0
toolz 1.1.0
fsspec 2026.2.0
zarr 3.1.6

---

Python 3.14.3 (main, Feb 3 2026, 15:32:20) [Clang 17.0.0 (clang-1700.6.3.2)]
OS macOS-15.1-arm64-arm-64bit-Mach-O
Updated 2026-05-08 12:45

[Zethson]

So what's the plan? Fixing this in AnnData & adding support in EHRData? Or making this a part of the AnnData spec?

[ilan-gold]

Or making this a part of the AnnData spec?

This is a can of worms. Updating the entire anndata spec is extremely disruptive given the number of downstream users of it, hence why I am hesitant to do it. Someone would need to shepherd the proposal through gathering community feedback, maybe altering the proposal etc. The other users of something like this would be scportrait where the shape of their images is (n_cells, n_channels, x, y) i.e., obs, var, other things.

My suggestion would probably be twofold - one, @eroell is working on a PR that would allow three dimensions in in-memory anndata objects in X (which would match layers). I think this is relatively fine, but doesn't solve your on-disk problem. But I discovered (from our conversation I didn't believe this to be the case) that there is another named dimension in EHRData i.e., the time dimension. I didn't realize it was so different i.e., including an entirely different key. So for this other part, you may want to propose a way of extending the anndata spec in general which https://treedata.readthedocs.io/en/latest/notebooks/getting-started.html also does informally

[flying-sheep]

why is this Triage 🩺 ?

[ilan-gold]

No reason