{"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":"exception","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/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_vendor/platformdirs/windows.py#L194-L230","documentation":"Raised as ValueError by get_win_folder_from_env_vars when a CSIDL constant resolves to an env-var name (APPDATA / LOCALAPPDATA / ALLUSERSPROFILE) but that environment variable is not set in os.environ. The message names the missing variable so the user knows what to provide.","triggerScenarios":"On Windows (or a Windows-like env without ctypes/winreg) the folder resolver falls back to environment variables; APPDATA/LOCALAPPDATA/ALLUSERSPROFILE is unset, so os.environ.get returns None and ValueError is raised.","commonSituations":"Running as a service account or in a container/minimal Windows env where these user-profile variables are not populated, or a corrupted user profile.","solutions":["Set the missing environment variable before launching the process (e.g. set APPDATA=%USERPROFILE%\\AppData\\Roaming).","Run under a normal interactive user account where the profile variables are populated.","Provide a WIN_PD_OVERRIDE_<NAME> env var so platformdirs uses the override path instead of the unset variable."],"exampleFix":"# before\n# APPDATA unset -> ValueError: Unset environment variable: APPDATA\n\n# after (shell, before running python)\nset APPDATA=%USERPROFILE%\\AppData\\Roaming\npython app.py","handlingStrategy":"validation","validationCode":"import os\nENV_FOR = {'CSIDL_APPDATA': 'APPDATA', 'CSIDL_COMMON_APPDATA': 'ALLUSERSPROFILE', 'CSIDL_LOCAL_APPDATA': 'LOCALAPPDATA'}\nenv_var = ENV_FOR.get(csidl_name)\nif env_var and env_var not in os.environ:\n    raise EnvironmentError(f'set {env_var} before resolving {csidl_name}')","typeGuard":"def env_var_set(name: str) -> bool:\n    import os\n    return name in os.environ","tryCatchPattern":"try:\n    p = get_win_folder_from_env_vars(name)\nexcept ValueError as e:\n    if 'Unset environment variable' in str(e):\n        var = str(e).split(':')[-1].strip()\n        os.environ[var] = default_for(var)  # set then retry\n    raise","preventionTips":["Ensure APPDATA/LOCALAPPDATA/ALLUSERSPROFILE are set for service/container accounts.","Use WIN_PD_OVERRIDE_* to avoid depending on user-profile variables."],"tags":["python","platformdirs","windows","environment","config"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}