{"record":{"id":"e7d2aced5edb1329","repo":"pandas-dev/pandas","slug":"arrowstringarray-requires-a-pyarrow-chunked-arra","errorCode":null,"errorMessage":"ArrowStringArray requires a PyArrow (chunked) array of large_string type","messagePattern":"ArrowStringArray requires a PyArrow \\(chunked\\) array of large_string type","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/string_arrow.py","lineNumber":166,"sourceCode":"            or (\n                pa.types.is_dictionary(values.type)\n                and (\n                    pa.types.is_string(values.type.value_type)\n                    or pa.types.is_large_string(values.type.value_type)\n                    or _is_string_view(values.type.value_type)\n                )\n            )\n        ):\n            values = pc.cast(values, pa.large_string())\n\n        super().__init__(values)\n\n        if dtype is None:\n            dtype = StringDtype(storage=\"pyarrow\", na_value=libmissing.NA)\n        self._dtype = dtype\n\n        if not pa.types.is_large_string(self._pa_array.type):\n            raise ValueError(\n                \"ArrowStringArray requires a PyArrow (chunked) array of \"\n                \"large_string type\"\n            )\n\n    def _from_pyarrow_array(self, pa_array):\n        \"\"\"\n        Construct from a pyarrow Array/ChunkedArray result of an operation.\n\n        Avoids full __init__ overhead (type checking, pc.cast, ArrowDtype\n        construction, etc.).\n        \"\"\"\n        assert isinstance(pa_array, (pa.Array, pa.ChunkedArray))\n        if not pa.types.is_large_string(pa_array.type):\n            pa_array = pa_array.cast(pa.large_string())\n        obj = type(self).__new__(type(self))\n        if isinstance(pa_array, pa.Array):\n            pa_array = pa.chunked_array([pa_array])\n        obj._pa_array = pa_array","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/pandas-dev/pandas/blob/3b7651241d4da534b3559b60ef128e1c34f54116/pandas/core/arrays/string_arrow.py#L148-L184","documentation":"ArrowStringArray.__init__ requires its underlying pyarrow array to be large_string type; if after attempted casting the array is still not pa.large_string, it raises ValueError. Internally pandas promotes string to large_string for compatibility, but a non-castable incoming type (e.g. binary, dictionary-encoded, or fixed-size binary) hits this guard.","triggerScenarios":"Constructing ArrowStringArray with a pa.string() that failed promotion, or passing pa.binary(), pa.dictionary(...), or a chunked array of mismatched string types; calling StringDtype('pyarrow').__from_arrow__(arr) with an incompatible array.","commonSituations":"Loading parquet whose column is binary/utf8 with a non-default encoding; converting from a pyarrow Table column that was cast to dictionary type; manually building ArrowStringArray from a computed pa.array.","solutions":["Cast the array explicitly: pa.chunked_array(arr).cast(pa.large_string()).","Construct via pd.array(list_or_series, dtype='string[pyarrow]') so pandas handles promotion.","If the source is binary, decode first: arr.cast(pa.string()).cast(pa.large_string()).","Use ArrowDtype(pa.string()) instead of forcing ArrowStringArray for non-large_string data."],"exampleFix":"// before\narr = pa.array([b'a', b'b'], type=pa.binary())\nArrowStringArray(arr)  # ValueError\n// after\narr = arr.cast(pa.large_string())\nArrowStringArray(arr)","handlingStrategy":"validation","validationCode":"def to_arrow_string_array(values):\n    import pyarrow as pa\n    if not pa.types.is_large_string(values.type):\n        values = values.cast(pa.large_string())\n    return values","typeGuard":"def is_large_string_array(arr) -> bool:\n    import pyarrow as pa\n    return pa.types.is_large_string(arr.type)","tryCatchPattern":"try:\n    ArrowStringArray(arr)\nexcept ValueError as e:\n    if 'large_string' in str(e):\n        ArrowStringArray(arr.cast(pa.large_string()))\n    else:\n        raise","preventionTips":["Cast pa.string to pa.large_string before constructing ArrowStringArray.","Decode binary columns before constructing.","Prefer pd.array(..., dtype='string[pyarrow]') for auto-promotion."],"tags":["pandas","pyarrow","arrow-string-array","dtype","casting"],"backgroundTag":null,"analyzedSha":"3b7651241d4da534b3559b60ef128e1c34f54116","analyzedAt":"2026-08-11T22:10:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}