{"record":{"id":"056b9b54b246cadf","repo":"pypa/pip","slug":"shgetknownfolderpath-returned-null-for-csidl-name","errorCode":null,"errorMessage":"SHGetKnownFolderPath returned NULL for {csidl_name}","messagePattern":"SHGetKnownFolderPath returned NULL for (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/pip/_vendor/platformdirs/windows.py","lineNumber":363,"sourceCode":"    kernel32.GetShortPathNameW.argtypes = [wintypes.LPWSTR, wintypes.LPWSTR, wintypes.DWORD]\n\n    def resolve(csidl_name: str) -> str:\n        folder_guid = _KNOWN_FOLDER_GUIDS.get(csidl_name)\n        if folder_guid is None:\n            msg = f\"Unknown CSIDL name: {csidl_name}\"\n            raise ValueError(msg)\n\n        guid = _GUID()\n        ole32.CLSIDFromString(folder_guid, byref(guid))\n\n        path_ptr = wintypes.LPWSTR()\n        shell32.SHGetKnownFolderPath(byref(guid), _KF_FLAG_DONT_VERIFY, None, byref(path_ptr))\n        result = path_ptr.value\n        ole32.CoTaskMemFree(path_ptr)\n\n        if result is None:\n            msg = f\"SHGetKnownFolderPath returned NULL for {csidl_name}\"\n            raise ValueError(msg)\n\n        if any(ord(c) > 255 for c in result):  # ruff:ignore[magic-value-comparison]\n            buf = create_unicode_buffer(1024)\n            if kernel32.GetShortPathNameW(result, buf, 1024):\n                result = buf.value\n\n        return result\n\n    return resolve\n\n\ndef get_win_folder_via_ctypes(csidl_name: str) -> str:\n    \"\"\"Get folder via :func:`SHGetKnownFolderPath`.\n\n    See https://learn.microsoft.com/en-us/windows/win32/api/shlobj_core/nf-shlobj_core-shgetknownfolderpath.\n\n    \"\"\"\n    return _build_get_win_folder_via_ctypes()(csidl_name)","sourceCodeStart":345,"sourceCodeEnd":381,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_vendor/platformdirs/windows.py#L345-L381","documentation":"Raised after the ctypes resolver calls shell32.SHGetKnownFolderPath for a known GUID and the returned pointer is NULL. A NULL result means Windows itself could not resolve the folder, even though the GUID was valid. This typically indicates the folder is not registered, not present on the current system, or the user profile is incomplete.","triggerScenarios":"SHGetKnownFolderPath returns a NULL LPWSTR (path_ptr.value is None) at windows.py:358-362, e.g. requesting CSIDL_COMMON_PROGRAMS in a stripped-down Windows environment, a corrupted user profile, or running under a service account whose profile lacks the folder.","commonSituations":"Running pip/platformdirs in a container, Windows Server Core, or a locked-down account where the Downloads/Pictures folder is not materialized; redirected/roamed folders that failed to provision; a broken user profile after a migration.","solutions":["Verify the user profile is complete (sign out/in or run 'systempropertiesadvanced' to rebuild profile folders).","Run under an interactive user account rather than SYSTEM/LocalService where the known folder may be absent.","Pre-create or redirect the missing known folder via the registry or Group Policy.","Fall back to an adjacent folder (e.g. LOCALAPPDATA) if the specific folder is optional to your logic."],"exampleFix":"try:\n    folder = get_win_folder_via_ctypes('CSIDL_DOWNLOADS')\nexcept ValueError:\n    folder = os.path.join(os.environ['USERPROFILE'], 'Downloads')","handlingStrategy":"fallback","validationCode":"null","typeGuard":"null","tryCatchPattern":"try:\n    folder = get_win_folder_via_ctypes(name)\nexcept ValueError as e:\n    if 'NULL' in str(e):\n        folder = os.path.join(os.environ.get('USERPROFILE',''), 'Downloads')\n    else:\n        raise","preventionTips":["Run under a profile that has the known folder materialized.","Provide a fallback path for environments like containers/Server Core where folders may be absent."],"tags":["python","platformdirs","windows","runtime","environment","vendored"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}