fix(metadata): read a legacy zero chunk size on an empty axis in Zarr format 3

The compatibility policy for a stored chunk size of 0 on a zero-length
axis covered Zarr format 2 only, so arrays written by zarr-python 3.0 and
3.1 with `chunk_shape: [0]` — or `[false]`, which 3.0 wrote for
`chunks=False` — still could not be opened at all.

`ArrayV3Metadata` now applies the same policy to a regular chunk grid: a
stored chunk size of 0 on a zero-length axis is read as 1 with a
`ZarrUserWarning`, and a zero chunk size on a positive-length axis is
left for the chunk grid parser to reject. It runs in `__init__` rather
than in the grid parser because the policy needs the array shape, which
chunk grid metadata does not carry.

Both warnings now say how to store a corrected chunk size — open the
array writable and call `array.update_attributes({})`, which rewrites the
whole document from the parsed metadata — from one shared constant. The
Zarr format 2 warning also named only zarr-python 2.x; measured against
real installs, every 3.x release before 3.4 wrote a zero chunk size for
an empty array too (3.3.0 for `chunks=-1` and `chunks=False`).

Tested against stores written by zarr 3.0.10, 3.1.6 and 3.3.0: they open,
append without losing data, and re-save to a chunk size that reopens
without a warning.

Assisted-by: ClaudeCode:claude-opus-5

Author: d-v-b

changes/4334.bugfix.md

@@ -1 +1,3 @@
-Chunk-grid normalization now shares a helper that selects chunk size 1 for a zero-length axis when inferring a full-span chunk size. Chunk edge lengths remain positive while array extents may be zero. Zarr format 2 metadata with a stored chunk edge of 0 on a zero-length axis is interpreted as chunk size 1 with a `ZarrUserWarning`; a zero chunk edge on a positive-length axis is rejected. This supports legacy metadata such as the zero chunk sizes written by zarr-python 2.18.7 for empty arrays created with `chunks=False`, `chunks=-1`, or `chunks=(0,)`, without claiming that every historical reader behaved identically. Rectilinear chunk grids can be created on a zero-length dimension with a non-empty list of positive chunk sizes; these sizes are retained for subsequent growth. `FixedDimension(size=0, ...)` now raises `ValueError`.
+Chunk-grid normalization now shares a helper that selects chunk size 1 for a zero-length axis when inferring a full-span chunk size. Chunk edge lengths remain positive while array extents may be zero. `FixedDimension(size=0, ...)` now raises `ValueError`. Rectilinear chunk grids can be created on a zero-length dimension with a non-empty list of positive chunk sizes; these sizes are retained for subsequent growth.
+
+A stored chunk size of 0 on a zero-length axis is read as 1 with a `ZarrUserWarning`, in both Zarr format 2 (`chunks`) and Zarr format 3 (a regular grid's `chunk_shape`, including the JSON `false` written by zarr-python 3.0 for `chunks=False`); a zero chunk size on a positive-length axis is rejected. zarr-python wrote such metadata for empty arrays until 3.4 — Zarr format 2 through 3.3 and by zarr-python 2.x, Zarr format 3 in 3.0 and 3.1 — and appending to one of these Zarr format 2 arrays previously reported success while writing no chunk, so the appended data read back as the fill value. The warning explains how to store a corrected chunk size: open the array writable and call `array.update_attributes({})`.

src/zarr/core/metadata/common.py

@@ -1,10 +1,20 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Final
 
 if TYPE_CHECKING:
     from zarr.core.common import JSON
 
+RESAVE_METADATA_HINT: Final = (
+    "Re-save the array metadata to store the corrected value: open the array "
+    "writable and call `array.update_attributes({})`."
+)
+"""How to persist metadata that was read under a compatibility policy.
+
+`update_attributes` rewrites the whole metadata document from the parsed
+(corrected) metadata, so an empty update is enough.
+"""
+
 
 def parse_attributes(data: dict[str, JSON] | None) -> dict[str, JSON]:
     if data is None:

src/zarr/core/metadata/v2.py

@@ -42,7 +42,7 @@
 )
 from zarr.core.config import config, parse_indexing_order
 from zarr.core.json_parse import parse_field
-from zarr.core.metadata.common import parse_attributes
+from zarr.core.metadata.common import RESAVE_METADATA_HINT, parse_attributes
 
 
 class ArrayV2MetadataDict(TypedDict):
@@ -90,8 +90,8 @@ def __init__(
         shape_parsed = parse_shapelike(shape)
         chunks_parsed = parse_shapelike(chunks)
         # Same invariant as the Zarr format 3 chunk grid metadata: every chunk edge
-        # length is at least 1. zarr-python 2.18.7 can write `chunks: [0]` for
-        # a zero-length axis created with `chunks=False`, `-1` or `(0,)`.
+        # length is at least 1. zarr-python 2.18.7, and 3.x before 3.4, can write
+        # `chunks: [0]` for a zero-length axis (e.g. `chunks=False`, `-1` or `(0,)`).
         # Normalize that empty axis to chunk size 1 so it can use the positive-size
         # grid model. This is a compatibility policy for legacy metadata, not a
         # statement about every historical reader. A zero chunk size on a
@@ -106,7 +106,8 @@ def __init__(
                     )
                 warnings.warn(
                     f"Dimension {dim_idx}: chunk edge length 0 on a zero-length axis "
-                    "(as written by zarr-python 2.x) is treated as 1.",
+                    "(as written by zarr-python 2.x, and by 3.x before 3.4) is treated "
+                    f"as 1. {RESAVE_METADATA_HINT}",
                     ZarrUserWarning,
                     stacklevel=2,
                 )

src/zarr/core/metadata/v3.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
 import json
+import warnings
 from collections.abc import Iterable, Mapping, Sequence
 from dataclasses import dataclass, field, replace
 from typing import TYPE_CHECKING, Any, Final, Literal, NotRequired, TypeGuard, cast
 
+import numpy as np
 from typing_extensions import TypedDict
 
 from zarr.abc.codec import ArrayArrayCodec, ArrayBytesCodec, BytesBytesCodec, Codec
@@ -35,8 +37,8 @@
 from zarr.core.dtype import VariableLengthUTF8, ZDType, get_data_type_from_json
 from zarr.core.dtype.common import check_dtype_spec_v3
 from zarr.core.json_parse import parse_field
-from zarr.core.metadata.common import parse_attributes
-from zarr.errors import MetadataValidationError, NodeTypeValidationError
+from zarr.core.metadata.common import RESAVE_METADATA_HINT, parse_attributes
+from zarr.errors import MetadataValidationError, NodeTypeValidationError, ZarrUserWarning
 from zarr.registry import get_codec_class
 
 if TYPE_CHECKING:
@@ -476,6 +478,51 @@ class ArrayMetadataJSON_V3(TypedDict, extra_items=AllowedExtraField):  # type: i
 }
 
 
+def _read_legacy_zero_chunk_sizes(
+    chunk_grid: dict[str, JSON] | ChunkGridMetadata | NamedConfig[str, Any],
+    shape: tuple[int, ...],
+) -> dict[str, JSON] | ChunkGridMetadata | NamedConfig[str, Any]:
+    """Read a stored regular chunk size of 0 on a zero-length axis as 1.
+
+    zarr-python 3.0 and 3.1 stored `chunk_shape: [0]` for an array created with
+    a zero-length axis and `chunks=(0,)` or `chunks=False` (3.0 stored `false`
+    for the latter). Chunk sizes must be at least 1, and a zero-length axis has
+    no chunks for the size to describe until the array grows, so the size is
+    read as 1 with a warning. This is the policy `ArrayV2Metadata` applies to
+    Zarr format 2 metadata. It needs the array shape, which the chunk grid
+    metadata does not carry, so it runs here rather than in the grid parser.
+    A zero chunk size on a positive-length axis is left for that parser to
+    reject.
+    """
+    if not isinstance(chunk_grid, Mapping) or chunk_grid.get("name") != "regular":
+        return chunk_grid
+    configuration = chunk_grid.get("configuration")
+    if not isinstance(configuration, Mapping):
+        return chunk_grid
+    chunk_shape = configuration.get("chunk_shape")
+    if not isinstance(chunk_shape, Sequence) or isinstance(chunk_shape, str):
+        return chunk_grid
+    if len(chunk_shape) != len(shape):
+        return chunk_grid  # the dimensionality check reports this
+    normalized = list(chunk_shape)
+    changed = False
+    for dim_idx, (size, extent) in enumerate(zip(chunk_shape, shape, strict=True)):
+        if isinstance(size, int | np.integer) and size == 0 and extent == 0:
+            warnings.warn(
+                f"Dimension {dim_idx}: chunk edge length {size!r} on a zero-length axis "
+                "(as written by zarr-python 3.0 and 3.1) is treated as 1. "
+                f"{RESAVE_METADATA_HINT}",
+                ZarrUserWarning,
+                stacklevel=2,
+            )
+            normalized[dim_idx] = 1
+            changed = True
+    if not changed:
+        return chunk_grid
+    corrected: dict[str, JSON] = {**configuration, "chunk_shape": normalized}
+    return {"name": "regular", "configuration": corrected}
+
+
 @dataclass(frozen=True, kw_only=True)
 class ArrayV3Metadata(Metadata):
     shape: tuple[int, ...]
@@ -510,7 +557,9 @@ def __init__(
         """
 
         shape_parsed = parse_shapelike(shape)
-        chunk_grid_parsed = parse_chunk_grid(chunk_grid)
+        chunk_grid_parsed = parse_chunk_grid(
+            _read_legacy_zero_chunk_sizes(chunk_grid, shape_parsed)
+        )
         chunk_key_encoding_parsed = parse_chunk_key_encoding(chunk_key_encoding)
         dimension_names_parsed = parse_dimension_names(dimension_names)
         # Note: relying on a type method is numpy-specific

tests/test_chunk_grids.py

@@ -1,4 +1,7 @@
 import contextlib
+import json
+import warnings
+from pathlib import Path
 from typing import Any, Literal, cast
 
 import numpy as np
@@ -541,6 +544,62 @@ def test_rectilinear_zero_extent_matches_resize() -> None:
         assert created.write_chunk_sizes == resized.write_chunk_sizes == ((2, 1),)
 
 
+def _store_legacy_zero_chunk(path: Any, zarr_format: Literal[2, 3], stored: Any) -> None:
+    """Rewrite an array's stored chunk size to *stored*, as older zarr-python did."""
+    doc_name = ".zarray" if zarr_format == 2 else "zarr.json"
+    doc_path = path / doc_name
+    doc = json.loads(doc_path.read_text())
+    if zarr_format == 2:
+        doc["chunks"] = [stored]
+    else:
+        doc["chunk_grid"]["configuration"]["chunk_shape"] = [stored]
+    doc_path.write_text(json.dumps(doc))
+
+
+@pytest.mark.parametrize("zarr_format", [2, 3])
+@pytest.mark.parametrize("stored", [0, False], ids=["zero", "false"])
+def test_legacy_zero_chunk_on_empty_axis_round_trip(
+    tmp_path: Path, zarr_format: Literal[2, 3], stored: Any
+) -> None:
+    """An empty array whose stored chunk size is 0 opens, appends without losing
+    data, and re-saves as a valid chunk size.
+
+    zarr-python wrote such metadata for an empty array until 3.4: Zarr format 2
+    through 3.3, and Zarr format 3 in 3.0 and 3.1, which also wrote JSON `false`
+    for `chunks=False`. Appending to one of these arrays used to report success
+    while writing no chunk, so the data read back as the fill value.
+    """
+    path = tmp_path / "legacy.zarr"
+    zarr.create_array(store=path, shape=(0,), chunks=(4,), dtype="int64", zarr_format=zarr_format)
+    _store_legacy_zero_chunk(path, zarr_format, stored)
+
+    with pytest.warns(ZarrUserWarning, match="zero-length axis"):
+        arr = zarr.open_array(store=path, mode="a")
+    assert arr.chunks == (1,)
+
+    arr.append(np.arange(3, dtype="int64"))
+    np.testing.assert_array_equal(zarr.open_array(store=path)[...], np.arange(3))
+
+    # The warning says to do this; it must leave metadata that reopens cleanly.
+    arr.update_attributes({})
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", ZarrUserWarning)
+        reopened = zarr.open_array(store=path)
+    assert reopened.chunks == (1,)
+
+
+@pytest.mark.parametrize("zarr_format", [2, 3])
+def test_stored_zero_chunk_on_positive_axis_rejected(
+    tmp_path: Path, zarr_format: Literal[2, 3]
+) -> None:
+    """A stored chunk size of 0 is only tolerated on a zero-length axis."""
+    path = tmp_path / "bad.zarr"
+    zarr.create_array(store=path, shape=(5,), chunks=(4,), dtype="int64", zarr_format=zarr_format)
+    _store_legacy_zero_chunk(path, zarr_format, 0)
+    with pytest.raises(ValueError, match="must be >= 1"):
+        zarr.open_array(store=path)
+
+
 def test_normalize_chunks_1d_zero_span_accepts_any_edges() -> None:
     """On a zero-length span the explicit edge list is stored verbatim."""
     dim = normalize_chunks_1d([3, 5], span=0)

tests/test_metadata/test_v3.py

@@ -463,3 +463,35 @@ def test_group_metadata_to_dict_consolidated(attributes: dict[str, Any] | None)
             },
         },
     }
+
+
+@pytest.mark.parametrize(
+    ("shape", "chunk_shape", "expected"),
+    [
+        ((0,), [0], (1,)),
+        ((4, 0), [4, 0], (4, 1)),
+        ((0, 0), [0, 0], (1, 1)),
+        ((0,), [False], (1,)),
+    ],
+    ids=["1d", "one-empty-axis", "all-empty-axes", "json-false"],
+)
+def test_zero_chunk_size_on_empty_axis_normalized(
+    shape: tuple[int, ...], chunk_shape: list[Any], expected: tuple[int, ...]
+) -> None:
+    """A stored regular chunk size of 0 on a zero-length axis is read as 1, with a warning.
+
+    zarr-python 3.0 and 3.1 wrote this for an array created with a zero-length
+    axis; 3.0 wrote JSON `false` for `chunks=False`. This is the Zarr format 3
+    counterpart of the policy `ArrayV2Metadata` applies.
+    """
+    from zarr.core.metadata.v3 import RegularChunkGridMetadata
+    from zarr.errors import ZarrUserWarning
+
+    d = minimal_metadata_dict_v3(
+        shape=shape,
+        chunk_grid={"name": "regular", "configuration": {"chunk_shape": chunk_shape}},
+    )
+    with pytest.warns(ZarrUserWarning, match="zero-length axis"):
+        meta = ArrayV3Metadata.from_dict(d)  # type: ignore[arg-type]
+    assert isinstance(meta.chunk_grid, RegularChunkGridMetadata)
+    assert meta.chunk_grid.chunk_shape == expected