{"record":{"id":"11f264b3488355a2","repo":"pypa/pip","slug":"unset-environment-variable-env-var-name","errorCode":null,"errorMessage":"Unset environment variable: {env_var_name}","messagePattern":"Unset environment variable: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/pip/_vendor/platformdirs/windows.py","lineNumber":212,"sourceCode":"\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\n    if csidl_name == \"CSIDL_MYVIDEO\":\n        return os.path.join(os.path.normpath(os.environ[\"USERPROFILE\"]), \"Videos\")  # ruff:ignore[os-path-join]\n\n    if csidl_name == \"CSIDL_MYMUSIC\":","sourceCodeStart":194,"sourceCodeEnd":230,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_vendor/platformdirs/windows.py#L194-L230","documentation":"Raised as ValueError in get_win_folder_from_env_vars() at line 211-212 when the CSIDL name is recognized but the corresponding environment variable (APPDATA, ALLUSERSPROFILE, or LOCALAPPDATA) is not set (None). This means the Windows shell environment is incomplete or the code is running in a non-standard Windows context where these variables are absent.","triggerScenarios":"Calling get_win_folder_from_env_vars for a valid CSIDL (e.g. CSIDL_APPDATA) but os.environ.get('APPDATA') returns None. This flows through get_win_folder -> _resolve_win_folder -> get_win_folder_from_env_vars on Windows systems using the env-var backend.","commonSituations":"Running as a Windows service or scheduled task that doesn't inherit user shell environment variables; broken Windows user profile; headless/containerized Windows where APPDATA/LOCALAPPDATA are unset; running under SYSTEM account without a user profile.","solutions":["Set the missing environment variable explicitly before calling platformdirs (e.g. set APPDATA or LOCALAPPDATA).","Use the ctypes backend (get_win_folder_via_ctypes) which calls SHGetKnownFolderPath and doesn't rely on env vars.","Ensure the process runs in a context with a complete user profile (interactive session, not bare service).","Provide fallback logic that computes the path manually (e.g. from USERPROFILE)."],"exampleFix":"// before\nget_win_folder('CSIDL_APPDATA')\n# ValueError: Unset environment variable: APPDATA\n\n// after\nimport os\nos.environ.setdefault('APPDATA', os.path.join(os.environ['USERPROFILE'], 'AppData', 'Roaming'))\nget_win_folder('CSIDL_APPDATA')","handlingStrategy":"validation","validationCode":"import os\nCSIDL_TO_ENV = {'CSIDL_APPDATA': 'APPDATA', 'CSIDL_COMMON_APPDATA': 'ALLUSERSPROFILE', 'CSIDL_LOCAL_APPDATA': 'LOCALAPPDATA'}\ndef env_var_is_set(csidl_name: str) -> bool:\n    env_var = CSIDL_TO_ENV.get(csidl_name)\n    return env_var is not None and os.environ.get(env_var) is not None","typeGuard":"import os\ndef win_env_available(env_var_name: str) -> bool:\n    return os.environ.get(env_var_name) is not None and bool(os.environ[env_var_name].strip())\n","tryCatchPattern":"import os\ntry:\n    folder = get_win_folder('CSIDL_APPDATA')\nexcept ValueError as e:\n    if 'Unset environment variable' in str(e):\n        env_var = str(e).split(': ')[-1]\n        folder = os.path.join(os.environ.get('USERPROFILE', 'C:\\\\Users\\\\Default'), 'AppData', 'Roaming')\n    else:\n        raise\n","preventionTips":["Ensure APPDATA, LOCALAPPDATA, and ALLUSERSPROFILE are set in service/scheduled-task environments.","Use get_win_folder_via_ctypes (SHGetKnownFolderPath) as fallback when env vars are absent.","Set fallback environment variables in headless/containerized Windows contexts."],"tags":["platform","platformdirs","windows","environment-variables","appdata"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}