[PDGGK]

Summary

zarr migrate v3 fails on any v2 array whose .zarray has "fill_value": null. That is valid in Zarr v2, and xarray writes it: Dataset.to_zarr(..., zarr_format=2) with xarray 2026.9.0 gives null for an int32 data variable and for an int64 coordinate. Migrating that store stops with

TypeError: Cannot convert object None with type <class 'NoneType'> to a scalar
compatible with the data type Int64(endianness='little').

and exit code 1. The cause is that _convert_array_metadata passes the v2 fill value straight to ArrayV3Metadata, which requires one.

The migrated metadata now uses dtype.default_scalar() when the v2 fill value is null. That is the value zarr-python already returns for chunks of the v2 array that were never written (fill_value_or_default in chunk_utils.py), so reading the migrated array gives the same result as reading the v2 array. It is also what create_array uses for a v3 array when fill_value=None.

test_migrate_null_fill_value creates a v2 array with fill_value=None for an int and a float dtype, writes one of its two chunks, migrates it through the CLI and checks the fill value and the data. Without the change both cases fail with assert 1 == 0 from the TypeError above. With it they pass, and the whole of tests/test_cli/test_migrate_v3.py passes (39 tests). I also ran zarr migrate v3 on the xarray-written store: it exits 0 and both arrays read back with fill value 0 and their data unchanged. ruff check, ruff format --check and codespell pass on the two files. mypy reports no new errors (the only ones are in _obstore.py, the same on unmodified main in my environment without obstore).

I did not run the full test suite, and I did not check other dtypes such as strings beyond what the parametrized test covers.

For reviewers

The choice of default_scalar() rather than, say, refusing to migrate is the part worth a look. I went with it because it keeps the visible values of unwritten chunks the same before and after migration.

Author attestation

• I am a human, these are my changes, and I have reviewed and understood every change and can explain why each is correct.

TODO

• Add unit tests and/or doctests in docstrings
• Add docstrings and API docs for any new/modified user-facing classes and functions
• New/modified features documented in docs/user-guide/*.md
• Changes documented as a new file in changes/
• GitHub Actions have all passed
• Test coverage is 100% (Codecov passes)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.90%. Comparing base (84a4992) to head (8359ede).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4616   +/-   ##
=======================================
  Coverage   94.90%   94.90%           
=======================================
  Files          96       96           
  Lines       14048    14051    +3     
=======================================
+ Hits        13332    13335    +3     
  Misses        716      716           

Files with missing lines	Coverage Δ
src/zarr/metadata/migrate_v3.py	98.41% <100.00%> (+0.03%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[d-v-b]

i think using the default scalar for the data type makes sense. we should also allow the user to define the new fill value.

but we also need to re-encode any partial chunks because the v2 null fill value made the contents of partial chunks implementation-dependent, and in v3 fill values don't work that way.

try adding a test case with a partially-written v2 chunk, and a new v3 fill value. reading the raw partially-written chunk in a v3 array should expose an incorrect fill value.

[d-v-b]

nvm, we can't do anything about partial chunks because there is no way to distinguish a partial chunk from a chunk written intentionally with the same values.