{"id":"866fabc2db4fa203","repo":"pypa/pip","slug":"unknown-csidl-name-csidl-name","errorCode":null,"errorMessage":"Unknown CSIDL name: {csidl_name}","messagePattern":"Unknown CSIDL name: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/pip/_vendor/platformdirs/windows.py","lineNumber":208,"sourceCode":"    def site_runtime_dir(self) -> str:\n        \"\"\"Runtime directory shared by users, same as `user_runtime_dir`.\"\"\"\n        return self.user_runtime_dir\n\n\ndef get_win_folder_from_env_vars(csidl_name: str) -> str:\n    \"\"\"Get folder from environment variables.\"\"\"\n    result = get_win_folder_if_csidl_name_not_env_var(csidl_name)\n    if result is not None:\n        return result\n\n    env_var_name = {\n        \"CSIDL_APPDATA\": \"APPDATA\",\n        \"CSIDL_COMMON_APPDATA\": \"ALLUSERSPROFILE\",\n        \"CSIDL_LOCAL_APPDATA\": \"LOCALAPPDATA\",\n    }.get(csidl_name)\n    if env_var_name is None:\n        msg = f\"Unknown CSIDL name: {csidl_name}\"\n        raise ValueError(msg)\n    result = os.environ.get(env_var_name)\n    if result is None:\n        msg = f\"Unset environment variable: {env_var_name}\"\n        raise ValueError(msg)\n    return result\n\n\ndef get_win_folder_if_csidl_name_not_env_var(csidl_name: str) -> str | None:  # ruff:ignore[too-many-return-statements]\n    \"\"\"Get a folder for a CSIDL name that does not exist as an environment variable.\"\"\"\n    if csidl_name == \"CSIDL_PERSONAL\":\n        return os.path.join(os.path.normpath(os.environ[\"USERPROFILE\"]), \"Documents\")  # ruff:ignore[os-path-join]\n\n    if csidl_name == \"CSIDL_DOWNLOADS\":\n        return os.path.join(os.path.normpath(os.environ[\"USERPROFILE\"]), \"Downloads\")  # ruff:ignore[os-path-join]\n\n    if csidl_name == \"CSIDL_MYPICTURES\":\n        return os.path.join(os.path.normpath(os.environ[\"USERPROFILE\"]), \"Pictures\")  # ruff:ignore[os-path-join]\n","sourceCodeStart":190,"sourceCodeEnd":226,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_vendor/platformdirs/windows.py#L190-L226","documentation":"Raised as ValueError by get_win_folder_from_env_vars when the requested csidl_name is neither handled by get_win_folder_if_csidl_name_not_env_var nor present in the {CSIDL_APPDATA, CSIDL_COMMON_APPDATA, CSIDL_LOCAL_APPDATA} env-var mapping. The message echoes the unknown CSIDL constant.","triggerScenarios":"Calling get_win_folder_from_env_vars(csidl_name) with a CSIDL constant not in the supported set (e.g. a typo like 'CSIDL_Dekstop' or an unsupported constant). This path is selected when neither ctypes nor winreg is available.","commonSituations":"A user override or custom code passing a wrong CSIDL name; running under a stripped-down Windows-like environment (no ctypes/winreg) so the env-var fallback path is used with an invalid name.","solutions":["Pass one of the supported CSIDL constants: CSIDL_APPDATA, CSIDL_COMMON_APPDATA, CSIDL_LOCAL_APPDATA (or the not-env-var ones like CSIDL_PERSONAL).","Avoid calling the internal get_win_folder_from_env_vars directly; use the public Windows()/platformdirs API which only emits valid constants.","Correct the typo in any WIN_PD_OVERRIDE_* environment variable name."],"exampleFix":"# before\nget_win_folder_from_env_vars('CSIDL_Dekstop')  # ValueError\n\n# after\nget_win_folder_from_env_vars('CSIDL_LOCAL_APPDATA')","handlingStrategy":"validation","validationCode":"KNOWN = {'CSIDL_APPDATA', 'CSIDL_COMMON_APPDATA', 'CSIDL_LOCAL_APPDATA',\n          'CSIDL_PERSONAL', 'CSIDL_DOWNLOADS', 'CSIDL_MYPICTURES',\n          'CSIDL_MYVIDEO', 'CSIDL_MYMUSIC', 'CSIDL_PROGRAMS', 'CSIDL_COMMON_PROGRAMS'}\nif csidl_name in KNOWN:\n    get_win_folder_from_env_vars(csidl_name)","typeGuard":"def is_known_csidl(name: str) -> bool:\n    return name in {'CSIDL_APPDATA','CSIDL_COMMON_APPDATA','CSIDL_LOCAL_APPDATA',\n                    'CSIDL_PERSONAL','CSIDL_DOWNLOADS','CSIDL_MYPICTURES',\n                    'CSIDL_MYVIDEO','CSIDL_MYMUSIC','CSIDL_PROGRAMS','CSIDL_COMMON_PROGRAMS'}","tryCatchPattern":"try:\n    p = get_win_folder_from_env_vars(name)\nexcept ValueError as e:\n    if 'Unknown CSIDL name' in str(e):\n        # name is unsupported; use a default\n        ...\n    raise","preventionTips":["Use the public platformdirs API rather than internal CSIDL helpers.","Whitelist CSIDL constants in your own code."],"tags":["python","platformdirs","windows","csidl","internal"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}