pandas-dev/pandas · error · ValueError

dtype '{dtype}' is invalid, should be np.timedelta64 dtype

Error message

dtype '{dtype}' is invalid, should be np.timedelta64 dtype

What it means

Raised by _validate_td64_dtype when the supplied dtype is not a numpy timedelta64 dtype at all (e.g. int64, float64, datetime64, object). The error names the offending dtype and states the expected kind.

Source

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

    # coerce Index to np.ndarray, converting string-dtype if necessary
    values = np.asarray(data, dtype=np.object_)

    result = array_to_timedelta64(values, unit=unit, errors=errors)
    return result


def _validate_td64_dtype(dtype) -> DtypeObj:
    dtype = pandas_dtype(dtype)
    if dtype == np.dtype("m8"):
        # no precision disallowed GH#24806
        msg = (
            "Passing in 'timedelta' dtype with no precision is not allowed. "
            "Please pass in 'timedelta64[ns]' instead."
        )
        raise ValueError(msg)

    if not lib.is_np_dtype(dtype, "m"):
        raise ValueError(f"dtype '{dtype}' is invalid, should be np.timedelta64 dtype")
    elif not is_supported_dtype(dtype):
        raise ValueError("Supported timedelta64 resolutions are 's', 'ms', 'us', 'ns'")

    return dtype

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Pass np.timedelta64 or a 'timedelta64[<unit>]' string.
2. Cross-check the dtype map keys against actual column semantics.
3. If you meant datetime, use datetime64[ns] instead.

Example fix

// before
idx = pd.TimedeltaIndex([1,2], dtype='int64')

// after
idx = pd.TimedeltaIndex([1,2], dtype='timedelta64[ns]')

import numpy as np
d = pandas_dtype(dtype)
if not lib.is_np_dtype(d, 'm'):
    raise ValueError(f'dtype {d} is not timedelta64')

def is_td_dtype(dtype) -> bool:
    import numpy as np
    from pandas.core.dtypes.common import pandas_dtype
    try:
        return lib.is_np_dtype(pandas_dtype(dtype), 'm')
    except TypeError:
        return False

try:
    idx = pd.TimedeltaIndex(data, dtype=dtype)
except ValueError as e:
    if 'should be np.timedelta64 dtype' in str(e):
        idx = pd.TimedeltaIndex(data, dtype='timedelta64[ns]')
    else:
        raise

When it happens

Trigger: `pd.TimedeltaIndex(data, dtype='int64')`, `.astype({'col':'datetime64[ns]'})` on a timedelta-typed object, or passing a non-timedelta dtype to APIs that validate the timedelta dtype.

Common situations: Wrong column in a dtype map; copy-paste from datetime code; programmatic dtype construction errors.

Related errors

• Passing in 'timedelta' dtype with no precision is not allowe
• Supported timedelta64 resolutions are 's', 'ms', 'us', 'ns'
• Column {colname} must have a numeric dtype. Found '{dtype}'
• codes need to be array-like integers
• {dtype=} does not have a resolution.

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