{"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":160,"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":142,"sourceCodeEnd":178,"githubUrl":"https://github.com/pandas-dev/pandas/blob/71959b8cb9b2459c16e14b34f28b178ccfe14735/pandas/core/arrays/string_arrow.py#L142-L178","documentation":"Raised in ArrowStringArray.__init__ after the super().__init__ call if the backing pyarrow array's type is not pa.large_string(). ArrowStringArray normalizes string/string_view/dictionary-of-string inputs to large_string (line 151), but if a non-string pyarrow type (e.g. int32, binary, or a fixed-size binary) is passed, the cast is skipped and the post-condition check at line 159 fails with ValueError. This protects the invariant that the underlying buffer is large_string-typed, which the string kernels depend on.","triggerScenarios":"Constructing ArrowStringArray directly from a pa.array of non-string type (e.g. pa.array([1,2,3]) or pa.array([b'a'], type=pa.binary())), or passing a ChunkedArray whose type survived the cast-skip branch. The check fires because pa.types.is_large_string(self._pa_array.type) is False.","commonSituations":"Manually wrapping a pyarrow array produced by compute kernels that changed type; passing binary() data expecting automatic utf8 decoding; interop code that assumes any pa.Array is acceptable.","solutions":["Cast the pyarrow array to large_string before construction: `pa_arr = pa_arr.cast(pa.large_string())`.","If the source is binary, decode first: `pc.cast(pa_arr, pa.large_string(), safe=False)` after confirming it is valid UTF-8.","Prefer the public pd.array(data, dtype='string[pyarrow]') constructor, which handles conversion, instead of ArrowStringArray(pa_arr) directly.","Verify the input type with `pa_arr.type` before passing it in."],"exampleFix":"# before\npa_arr = pa.array([b'a', b'b'], type=pa.binary())\nArrowStringArray(pa_arr)  # ValueError\n# after\npa_arr = pa_arr.cast(pa.large_string())\nArrowStringArray(pa_arr)","handlingStrategy":"validation","validationCode":"import pyarrow as pa\n\ndef to_arrow_string_array(values):\n    if not pa.types.is_large_string(values.type):\n        if pa.types.is_string(values.type) or pa.types.is_binary(values.type):\n            values = values.cast(pa.large_string())\n        else:\n            raise ValueError(f'Unsupported pyarrow type: {values.type}')\n    return values","typeGuard":"import pyarrow as pa\ndef is_large_string_array(arr) -> bool:\n    return pa.types.is_large_string(getattr(arr, 'type', None))","tryCatchPattern":"try:\n    from pandas.core.arrays.string_arrow import ArrowStringArray\n    ArrowStringArray(pa_arr)\nexcept ValueError as e:\n    if 'large_string' in str(e):\n        pa_arr = pa_arr.cast(pa.large_string())\n    else:\n        raise","preventionTips":["Always pass data through pd.array(..., dtype='string[pyarrow]') instead of the raw constructor.","Inspect pa_arr.type before wrapping; assert it is string/large_string.","Decode binary payloads explicitly with pc.cast before handing to pandas."],"tags":["pyarrow","string-arrow","dtype-mismatch","valueerror"],"analyzedSha":"71959b8cb9b2459c16e14b34f28b178ccfe14735","analyzedAt":"2026-08-07T01:30:20.476Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}