{"record":{"id":"c5e3852556ca83d9","repo":"pandas-dev/pandas","slug":"value-should-be-a-period-got-value-instead","errorCode":null,"errorMessage":"'value' should be a Period. Got '{value}' instead.","messagePattern":"'value' should be a Period\\. Got '(.+?)' instead\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/period.py","lineNumber":388,"sourceCode":"        return cls._simple_new(subarr, dtype=dtype)\n\n    # -----------------------------------------------------------------\n    # DatetimeLike Interface\n\n    def _unbox_scalar(\n        self,\n        # error: Argument 1 of \"_unbox_scalar\" is incompatible with supertype\n        # \"pandas.core.arrays.datetimelike.DatetimeLikeArrayMixin\"; supertype\n        #  defines the argument type as \"Period | Timestamp | Timedelta | NaTType\"\n        value: Period | NaTType,  # type: ignore[override]\n    ) -> np.int64:\n        if value is NaT:\n            return np.int64(value._value)\n        elif isinstance(value, self._scalar_type):\n            self._check_compatible_with(value)\n            return np.int64(value.ordinal)\n        else:\n            raise ValueError(f\"'value' should be a Period. Got '{value}' instead.\")\n\n    def _scalar_from_string(self, value: str) -> Period:\n        return Period(value, freq=self.freq)\n\n    def _check_compatible_with(\n        self,\n        #  error: Argument 1 of \"_check_compatible_with\" is incompatible with\n        # supertype \"pandas.core.arrays.datetimelike.DatetimeLikeArrayMixin\";\n        # supertype defines the argument type as \"Period | Timestamp | Timedelta\n        # | NaTType\"\n        other: Period | NaTType | PeriodArray,  # type: ignore[override]\n    ) -> None:\n        if other is NaT:\n            return\n        elif isinstance(other, Period):\n            self._require_matching_unit(other._dtype._freqstr)\n        else:\n            # error: Item \"NaTType\" of \"NaTType | PeriodArray\" has no","sourceCodeStart":370,"sourceCodeEnd":406,"githubUrl":"https://github.com/pandas-dev/pandas/blob/71959b8cb9b2459c16e14b34f28b178ccfe14735/pandas/core/arrays/period.py#L370-L406","documentation":"Raised by PeriodArray._unbox_scalar when the value is neither NaT nor a Period instance. _unbox_scalar converts a scalar into the int64 ordinal storage; only Period (and NaT) carry the frequency context required, so any other scalar (Timestamp, str, int) is rejected.","triggerScenarios":"Assignment/searchset operations that route a scalar through _unbox_scalar: pa[0] = '2020-01-01', pa.searchsorted(some_timestamp), fillna with a non-Period value on a period Series.","commonSituations":"Trying to assign a string or Timestamp into a period array. fillna with a Python int instead of pd.Period. Cross-dtype operations mixing period and datetime scalars.","solutions":["Wrap the scalar: pa[i] = pd.Period('2020-01-01', freq=pa.freq).","Use NaT for missing values: pa[i] = pd.NaT.","Match the Period's freq to the array's freq to avoid downstream IncompatibleFrequency."],"exampleFix":"# before\npa = pd.period_array(['2020-01-01','2020-01-02'], dtype=pd.PeriodDtype('D'))\npa[0] = '2021-01-01'\n# after\npa[0] = pd.Period('2021-01-01', freq='D')","handlingStrategy":"type-guard","validationCode":"import pandas as pd\n\ndef to_period_scalar(value, freq):\n    if value is pd.NaT or isinstance(value, pd.Period):\n        return value\n    return pd.Period(value, freq=freq)","typeGuard":"import pandas as pd\n\ndef is_period_or_nat(value) -> bool:\n    return value is pd.NaT or isinstance(value, pd.Period)","tryCatchPattern":"try:\n    pa[i] = value\nexcept ValueError:\n    pa[i] = pd.Period(value, freq=pa.freq)","preventionTips":["Always box scalars as pd.Period(..., freq=array.freq) before assigning.","Use pd.NaT (not None/NaN) for missing period values.","Keep freq consistent between scalars and the target array."],"tags":["period","scalar","setitem","pandas-arrays"],"analyzedSha":"71959b8cb9b2459c16e14b34f28b178ccfe14735","analyzedAt":"2026-08-07T01:30:20.476Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}