{"record":{"id":"866fabc2db4fa203","repo":"pypa/pip","slug":"unknown-csidl-name-csidl-name","errorCode":null,"errorMessage":"Unknown CSIDL name: {csidl_name}","messagePattern":"Unknown CSIDL name: (.+?)","errorType":"validation","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/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_vendor/platformdirs/windows.py#L190-L226","documentation":"Raised as ValueError in get_win_folder_from_env_vars() at line 207-208 when the csidl_name is not one of the three recognized CSIDL constants (CSIDL_APPDATA, CSIDL_COMMON_APPDATA, CSIDL_LOCAL_APPDATA). The function maps CSIDL names to Windows environment variables; an unmapped name means the caller passed an unsupported CSIDL identifier.","triggerScenarios":"Calling get_win_folder_from_env_vars with a csidl_name not in the {CSIDL_APPDATA, CSIDL_COMMON_APPDATA, CSIDL_LOCAL_APPDATA} mapping. This can happen via get_win_folder() -> _resolve_win_folder() chain when an unsupported CSIDL name is requested on a system using the env-var fallback strategy.","commonSituations":"Passing an incorrect CSIDL constant; internal platformdirs code requesting a folder type that the env-var backend doesn't support; corrupted or monkeypatched CSIDL constants; using the wrong backend function for the requested folder.","solutions":["Only pass valid CSIDL names: 'CSIDL_APPDATA', 'CSIDL_COMMON_APPDATA', 'CSIDL_LOCAL_APPDATA'.","Use the top-level get_win_folder() dispatcher which routes to the correct backend (registry, ctypes, or env vars).","Check _KNOWN_FOLDER_GUIDS keys for the full set of supported names when using the ctypes backend.","Avoid calling get_win_folder_from_env_vars directly; it is an internal backend function."],"exampleFix":"// before\nget_win_folder_from_env_vars('CSIDL_PERSONAL')\n# ValueError: Unknown CSIDL name: CSIDL_PERSONAL\n\n// after\nfrom pip._vendor.platformdirs.windows import get_win_folder\nfolder = get_win_folder('CSIDL_PERSONAL')  # routes to correct backend","handlingStrategy":"validation","validationCode":"VALID_CSIDL_ENV = {'CSIDL_APPDATA', 'CSIDL_COMMON_APPDATA', 'CSIDL_LOCAL_APPDATA'}\ndef is_env_backed_csidl(csidl_name: str) -> bool:\n    return csidl_name in VALID_CSIDL_ENV","typeGuard":"VALID_CSIDL = {'CSIDL_APPDATA', 'CSIDL_COMMON_APPDATA', 'CSIDL_LOCAL_APPDATA',\n    'CSIDL_PERSONAL', 'CSIDL_DOWNLOADS', 'CSIDL_MYPICTURES', 'CSIDL_MYVIDEO', 'CSIDL_MYMUSIC', 'CSIDL_PROGRAMS'}\ndef is_known_csidl(name: str) -> bool:\n    return name in VALID_CSIDL\n","tryCatchPattern":"try:\n    folder = get_win_folder_from_env_vars(csidl_name)\nexcept ValueError:\n    folder = get_win_folder(csidl_name)  # try full dispatcher\n","preventionTips":["Use get_win_folder() dispatcher instead of calling get_win_folder_from_env_vars directly.","Validate CSIDL names against known constants before passing to backend functions.","Reference _KNOWN_FOLDER_GUIDS for the complete set of supported names."],"tags":["platform","platformdirs","windows","csidl","environment"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}