{"record":{"id":"a63c00064058bd73","repo":"pandas-dev/pandas","slug":"value-must-be-one-of-python-pyarrow","errorCode":null,"errorMessage":"Value must be one of python|pyarrow","messagePattern":"Value must be one of python\\|pyarrow","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/core/config_init.py","lineNumber":500,"sourceCode":"    cf.register_option(\n        \"max_threads\",\n        None,\n        max_threads_doc,\n        validator=_is_positive_int_or_none,\n    )\n\n\nstring_storage_doc = \"\"\"\n: string\n    The default storage for StringDtype.\n\"\"\"\n\n\ndef is_valid_string_storage(value: Any) -> None:\n    legal_values = [\"auto\", \"python\", \"pyarrow\"]\n    if value not in legal_values:\n        msg = \"Value must be one of python|pyarrow\"\n        raise ValueError(msg)\n\n\nwith cf.config_prefix(\"mode\"):\n    cf.register_option(\n        \"string_storage\",\n        \"auto\",\n        string_storage_doc,\n        # validator=is_one_of_factory([\"python\", \"pyarrow\"]),\n        validator=is_valid_string_storage,\n    )\n\n\n# Set up the io.excel specific reader configuration.\nreader_engine_doc = \"\"\"\n: string\n    The default Excel reader engine for '{ext}' files. Available options:\n    auto, {others}.\n\"\"\"","sourceCodeStart":482,"sourceCodeEnd":518,"githubUrl":"https://github.com/pandas-dev/pandas/blob/71959b8cb9b2459c16e14b34f28b178ccfe14735/pandas/core/config_init.py#L482-L518","documentation":"ValueError raised by is_valid_string_storage() in pandas/core/config_init.py:500, the validator for the 'mode.string_storage' option which selects the default backing dtype for StringDtype. The function's legal_values list actually permits ['auto','python','pyarrow'], but the error message only mentions 'python|pyarrow' (a known message/behavior mismatch worth noting). Any other value raises at set-option time.","triggerScenarios":"pd.set_option('mode.string_storage', 'Arrow'); pd.set_option('mode.string_storage', 'str'); pd.set_option('mode.string_storage', 'numpy'); misspelled 'pyarow'; passing a non-string value such as None, True, or an int; reading the value from config and passing it unvalidated.","commonSituations":"Confusing the option value with the dtype name (e.g. 'StringDtype', 'ArrowDtype'); using a casing the validator does not normalize ('Python', 'PyArrow'); older pandas versions that only accepted 'python'/'pyarrow' before 'auto' was added; env/config-driven setups that pass through arbitrary strings; users assuming 'numpy' object storage is selectable here (it is not).","solutions":["Use one of the exact lowercase tokens: 'auto', 'python', or 'pyarrow'.","Install pyarrow before selecting 'pyarrow' (it raises a separate ImportError otherwise).","Normalize config input: value = str(value).strip().lower(); if value not in {'auto','python','pyarrow'}: keep default rather than calling set_option.","Note the message says 'python|pyarrow' but 'auto' is also accepted in recent versions; prefer 'auto' to defer the choice based on pyarrow availability."],"exampleFix":"// before\npd.set_option('mode.string_storage', 'PyArrow')  # ValueError\n\n// after\npd.set_option('mode.string_storage', 'pyarrow')\n# or, to defer to availability:\npd.set_option('mode.string_storage', 'auto')","handlingStrategy":"validation","validationCode":"import pandas as pd\n\n_VALID_STRING_STORAGE = {'auto', 'python', 'pyarrow'}\n\ndef set_string_storage(value: str) -> None:\n    v = str(value).strip().lower()\n    if v not in _VALID_STRING_STORAGE:\n        raise ValueError(f'string_storage must be one of {sorted(_VALID_STRING_STORAGE)}, got {value!r}')\n    if v == 'pyarrow':\n        try:\n            import pyarrow  # noqa: F401\n        except ImportError as e:\n            raise ImportError('mode.string_storage=pyarrow requires pyarrow installed') from e\n    pd.set_option('mode.string_storage', v)","typeGuard":"def is_valid_string_storage(value) -> bool:\n    return isinstance(value, str) and value.strip().lower() in {'auto', 'python', 'pyarrow'}","tryCatchPattern":"import pandas as pd\n\ntry:\n    pd.set_option('mode.string_storage', value)\nexcept ValueError as e:\n    if 'python|pyarrow' in str(e) or 'string_storage' in str(e):\n        # keep current default; do not crash the app over a config typo\n        pd.set_option('mode.string_storage', 'auto')\n    else:\n        raise","preventionTips":["Normalize to lowercase and strip whitespace before set_option.","Use 'auto' when you do not need to force a backend; it picks pyarrow if installed.","Ensure pyarrow is installed before selecting 'pyarrow'.","Validate config-file values against the fixed set {'auto','python','pyarrow'} on load."],"tags":["config","options","string-dtype","pyarrow","validation"],"analyzedSha":"71959b8cb9b2459c16e14b34f28b178ccfe14735","analyzedAt":"2026-08-07T01:30:20.476Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}