pandas-dev/pandas · error · ValueError

Values resolution does not match dtype.

Error message

Values resolution does not match dtype.

What it means

Raised by TimedeltaArray._validate_dtype() when the explicitly requested dtype's resolution does not match the resolution of the supplied values array. TimedeltaArray is resolution-aware (s/ms/us/ns), and _simple_new requires values.dtype to equal dtype exactly; a mismatch means the caller asked for one unit while the data carries another, which would silently misinterpret magnitudes. The guard rejects the combination rather than guessing a conversion.

Source

Thrown at pandas/core/arrays/timedeltas.py:230

        -------
        numpy.dtype
        """
        return self._ndarray.dtype

    @property  # NB: override with cache_readonly in immutable subclasses
    def _resolution_obj(self) -> Resolution:
        return get_resolution(self.asi8, tz=None, reso=self._creso)

    # ----------------------------------------------------------------
    # Constructors

    @classmethod
    def _validate_dtype(cls, values, dtype):
        # used in TimeLikeOps.__init__
        dtype = _validate_td64_dtype(dtype)
        _validate_td64_dtype(values.dtype)
        if dtype != values.dtype:
            raise ValueError("Values resolution does not match dtype.")
        return dtype

    # error: Signature of "_simple_new" incompatible with supertype "NDArrayBacked"
    @classmethod
    def _simple_new(  # type: ignore[override]
        cls,
        values: npt.NDArray[np.timedelta64],
        dtype: np.dtype[np.timedelta64] = TD64NS_DTYPE,
    ) -> Self:
        # Require td64 dtype, not unit-less, matching values.dtype
        assert lib.is_np_dtype(dtype, "m")
        assert not tslibs.is_unitless(dtype)
        assert isinstance(values, np.ndarray), type(values)
        assert dtype == values.dtype

        return super()._simple_new(values=values, dtype=dtype)

    @classmethod

View on GitHub (pinned to 71959b8cb9)

Solutions

  1. Align the dtype unit with the values: pass dtype=np.dtype('timedelta64[s]') matching values.view('m8[s]').
  2. Convert values to the desired unit first via astype_overflowsafe before constructing.
  3. Use the public TimedeltaIndex/timedelta_range constructors, which handle unit alignment, instead of _simple_new.

Example fix

# before
vals = np.array([1,2,3], dtype='timedelta64[s]')
TimedeltaArray._simple_new(vals, dtype=np.dtype('timedelta64[ns]'))  # ValueError
# after
TimedeltaArray._simple_new(vals, dtype=vals.dtype)
Defensive patterns

Strategy: validation

Validate before calling

import numpy as np

def build_td_array(values, dtype=None):
    if dtype is not None and dtype != values.dtype:
        from pandas._libs.tslibs import astype_overflowsafe
        values = astype_overflowsafe(values, dtype=dtype, copy=False)
    return values

Type guard

import numpy as np
def resolutions_match(values, dtype) -> bool:
    return dtype is None or dtype == values.dtype

Try / catch

try:
    return TimedeltaArray._simple_new(vals, dtype=dtype)
except ValueError as e:
    if 'resolution does not match' in str(e):
        return TimedeltaArray._simple_new(vals, dtype=vals.dtype)
    raise

Prevention

When it happens

Trigger: Calling TimedeltaArray._simple_new or _validate_dtype with e.g. values of dtype timedelta64[s] but dtype=timedelta64[ns]. Internal to pandas; surfaces via low-level constructors or extension code that hand-builds a TimedeltaArray.

Common situations: Custom extension types wrapping TimedeltaArray; tests that construct arrays with mismatched unit args; bugs in code paths that pass a pre-converted ndarray but a stale dtype.

Related errors

AI-assisted analysis of pandas-dev/pandas@71959b8cb9 (2026-08-07). Data as JSON: /api/errors/43e71ff706d0b281. Report an issue: GitHub.