{"record":{"id":"56abe5bc8b3a1611","repo":"pandas-dev/pandas","slug":"unexpected-value-for-dtype-dtype-must-be","errorCode":null,"errorMessage":"Unexpected value for 'dtype': '{dtype}'. Must be 'datetime64[s]', 'datetime64[ms]', 'datetime64[us]', 'datetime64[ns]' or DatetimeTZDtype'.","messagePattern":"Unexpected value for 'dtype': '(.+?)'\\. Must be 'datetime64\\[s\\]', 'datetime64\\[ms\\]', 'datetime64\\[us\\]', 'datetime64\\[ns\\]' or DatetimeTZDtype'\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/datetimes.py","lineNumber":2988,"sourceCode":"    -----\n    Unlike _validate_tz_from_dtype, this does _not_ allow non-existent\n    tz errors to go through\n    \"\"\"\n    if dtype is not None:\n        dtype = pandas_dtype(dtype)\n        if dtype == np.dtype(\"M8\"):\n            # no precision, disallowed GH#24806\n            msg = (\n                \"Passing in 'datetime64' dtype with no precision is not allowed. \"\n                \"Please pass in 'datetime64[ns]' instead.\"\n            )\n            raise ValueError(msg)\n\n        if (\n            isinstance(dtype, np.dtype)\n            and (dtype.kind != \"M\" or not is_supported_dtype(dtype))\n        ) or not isinstance(dtype, (np.dtype, DatetimeTZDtype)):\n            raise ValueError(\n                f\"Unexpected value for 'dtype': '{dtype}'. \"\n                \"Must be 'datetime64[s]', 'datetime64[ms]', 'datetime64[us]', \"\n                \"'datetime64[ns]' or DatetimeTZDtype'.\"\n            )\n\n        if getattr(dtype, \"tz\", None):\n            # https://github.com/pandas-dev/pandas/issues/18595\n            # Ensure that we have a standard timezone for pytz objects.\n            # Without this, things like adding an array of timedeltas and\n            # a  tz-aware Timestamp (with a tz specific to its datetime) will\n            # be incorrect(ish?) for the array as a whole\n            dtype = cast(\"DatetimeTZDtype\", dtype)\n            dtype = DatetimeTZDtype(\n                unit=dtype.unit, tz=timezones.tz_standardize(dtype.tz)\n            )\n\n    return dtype\n","sourceCodeStart":2970,"sourceCodeEnd":3006,"githubUrl":"https://github.com/pandas-dev/pandas/blob/3b7651241d4da534b3559b60ef128e1c34f54116/pandas/core/arrays/datetimes.py#L2970-L3006","documentation":"Raised by _validate_dt64_dtype when the supplied dtype is a numpy dtype that is not an 'M' kind or is not a supported datetime resolution, OR is not a numpy.dtype / DatetimeTZDtype instance at all. The message enumerates the supported values. This is the catch-all dtype validation for datetime construction.","triggerScenarios":"Passing `dtype='int64'`, `dtype='float64'`, `dtype='object'`, `dtype='datetime64[fs]'` (unsupported unit), `dtype='category'`, or any non-datetime dtype to a DatetimeIndex/DatetimeArray constructor routed through _validate_dt64_dtype.","commonSituations":"Typo in a unit string (e.g. 'datetime64[n]'). Confusing a Series constructor (which accepts any dtype) with a DatetimeIndex constructor (which only accepts datetime dtypes). Programmatic code that passes whatever dtype a column currently has into a datetime-conversion call.","solutions":["Verify the dtype string matches one of the supported forms exactly: 'datetime64[s]', 'datetime64[ms]', 'datetime64[us]', 'datetime64[ns]', or a DatetimeTZDtype like 'datetime64[ns, UTC]'.","If the data is not yet datetime, first convert with `pd.to_datetime(values)` and only then specify a datetime dtype.","If you wanted a non-datetime dtype, use `pd.Series` not `pd.DatetimeIndex`.","For tz-aware targets, prefer constructing a DatetimeTZDtype object explicitly: `pd.DatetimeTZDtype(tz='UTC', unit='ns')`."],"exampleFix":"// before\ndti = pd.DatetimeIndex(values, dtype='datetime64[n]')\n\n// after\ndti = pd.DatetimeIndex(values, dtype='datetime64[ns]')","handlingStrategy":"validation","validationCode":"import pandas as pd\n\nVALID = {'datetime64[s]', 'datetime64[ms]', 'datetime64[us]', 'datetime64[ns]'}\ndef is_supported_dt_dtype_string(s: str) -> bool:\n    if s in VALID:\n        return True\n    try:\n        return isinstance(pd.DatetimeTZDtype.construct_from_string(s), pd.DatetimeTZDtype)\n    except TypeError:\n        return False","typeGuard":"import pandas as pd\ndef is_datetime_dtype_spec(s) -> bool:\n    try:\n        dt = pd.api.types.pandas_dtype(s)\n    except TypeError:\n        return False\n    return isinstance(dt, (np.dtype, pd.DatetimeTZDtype)) and (dt.kind == 'M' or isinstance(dt, pd.DatetimeTZDtype))","tryCatchPattern":"try:\n    dti = pd.DatetimeIndex(values, dtype=dtype_str)\nexcept ValueError as e:\n    if \"Unexpected value for 'dtype'\" in str(e):\n        dti = pd.DatetimeIndex(values)  # let pandas pick\n    else:\n        raise","preventionTips":["Whitelist supported datetime dtype strings in configuration surfaces.","Prefer omitting dtype and letting pandas infer when in doubt."],"tags":["datetime","dtype","construction","validation"],"backgroundTag":null,"analyzedSha":"3b7651241d4da534b3559b60ef128e1c34f54116","analyzedAt":"2026-08-11T22:10:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}