{"record":{"id":"3193d7aa6d98fdf4","repo":"pandas-dev/pandas","slug":"must-specify-a-valid-frequency-freq","errorCode":null,"errorMessage":"Must specify a valid frequency: {freq}","messagePattern":"Must specify a valid frequency: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/arrow/array.py","lineNumber":4177,"sourceCode":"\n    def _dt_strftime(self, format: str) -> Self:\n        result = pc.strftime(self._pa_array, format=format)\n        return self._from_pyarrow_array(result)\n\n    def _round_temporally(\n        self,\n        method: Literal[\"ceil\", \"floor\", \"round\"],\n        freq,\n        ambiguous: TimeAmbiguous = \"raise\",\n        nonexistent: TimeNonexistent = \"raise\",\n    ) -> Self:\n        if ambiguous != \"raise\":\n            raise NotImplementedError(\"ambiguous is not supported.\")\n        if nonexistent != \"raise\":\n            raise NotImplementedError(\"nonexistent is not supported.\")\n        offset = to_offset(freq)\n        if offset is None:\n            raise ValueError(f\"Must specify a valid frequency: {freq}\")\n        pa_supported_unit = {\n            \"Y\": \"year\",\n            \"YS\": \"year\",\n            \"Q\": \"quarter\",\n            \"QS\": \"quarter\",\n            \"M\": \"month\",\n            \"MS\": \"month\",\n            \"W\": \"week\",\n            \"D\": \"day\",\n            \"h\": \"hour\",\n            \"min\": \"minute\",\n            \"s\": \"second\",\n            \"ms\": \"millisecond\",\n            \"us\": \"microsecond\",\n            \"ns\": \"nanosecond\",\n        }\n        unit = pa_supported_unit.get(offset._prefix, None)\n        if unit is None:","sourceCodeStart":4159,"sourceCodeEnd":4195,"githubUrl":"https://github.com/pandas-dev/pandas/blob/71959b8cb9b2459c16e14b34f28b178ccfe14735/pandas/core/arrays/arrow/array.py#L4159-L4195","documentation":"Raised by ArrowExtensionArray._round_temporally when pandas.tseries.frequencies.to_offset(freq) returns None, i.e. the `freq` string cannot be parsed as a valid pandas offset alias. The pyarrow rounding path requires a recognized frequency to map to a pyarrow temporal unit. Reached through dt.ceil/floor/round on a pyarrow-backed timestamp Series.","triggerScenarios":"Calling `s.dt.floor(\"xyz\")`, `s.dt.round(\"\")`, `s.dt.ceil(None)` (where None is passed positionally), or any unparseable/non-string freq on timestamp[pyarrow]. Also when freq is a malformed alias like '1X'.","commonSituations":"Typos in freq strings; dynamically building freq from user input; passing a numeric instead of a string; confusing the freq alias with a DateOffset object that to_offset cannot parse.","solutions":["Use a valid alias: 's','min','h','D','W','M','MS','Q','QS','Y','YS','ms','us','ns' optionally prefixed by a multiple like '30min'.","Validate with `pd.tseries.frequencies.to_offset(freq)` before calling; if it returns None, reject early.","Pass a DateOffset instance that to_offset understands, e.g. `pd.offsets.Hour()`.","Check for trailing/leading whitespace or typos in the string."],"exampleFix":"# before\ns.dt.floor(\"30mins\")  # typo -> ValueError\n\n# after\ns.dt.floor(\"30min\")","handlingStrategy":"validation","validationCode":"from pandas.tseries.frequencies import to_offset\n\ndef is_valid_freq(freq) -> bool:\n    try:\n        return to_offset(freq) is not None\n    except (ValueError, TypeError):\n        return False\n\ndef safe_round(s, freq, method=\"floor\"):\n    if not is_valid_freq(freq):\n        raise ValueError(f\"Invalid frequency: {freq!r}\")\n    return s.dt.__getattribute__(method)(freq)","typeGuard":"from pandas.tseries.frequencies import to_offset\n\ndef is_valid_freq(freq) -> bool:\n    try:\n        return to_offset(freq) is not None\n    except Exception:\n        return False","tryCatchPattern":"try:\n    out = s.dt.floor(freq)\nexcept ValueError as e:\n    if \"valid frequency\" in str(e):\n        raise ValueError(f\"Fix freq alias: {freq!r}. Valid: s,min,h,D,W,M,MS,Q,QS,Y,YS,ms,us,ns\") from e\n    raise","preventionTips":["Validate freq with to_offset() before rounding.","Whitelist supported freq aliases in config-driven code.","Pass DateOffset instances instead of strings when possible."],"tags":["pyarrow","datetime-accessor","frequency","validation"],"analyzedSha":"71959b8cb9b2459c16e14b34f28b178ccfe14735","analyzedAt":"2026-08-07T01:30:20.476Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}