GetLastError

GetLastError is a Windows API function that retrieves the calling thread’s last-error code. It returns a DWORD that represents the most recent error value for the current thread, which is stored in thread-local storage and is separate from other threads’ error states. If no error has occurred on the thread, the return value is typically ERROR_SUCCESS (0).

Usage and behavior

GetLastError is used to obtain extended error information after a Windows API function signals failure. It is important to call GetLastError immediately after the failing function indicates an error, because subsequent API calls can overwrite the last-error value. The last-error code is meaningful only for the thread that invoked the failing call and only if the function reports an error or sets an error condition.

Error codes and interpretation

The value returned by GetLastError is a Windows system error code (DWORD). Many errors are defined in Winerror.h, such as ERROR_FILE_NOT_FOUND, ERROR_PATH_NOT_FOUND, and ERROR_ACCESS_DENIED. The numeric code can be translated to a human-readable message using utilities like FormatMessage. Note that some functions may not set GetLastError on success, and some may clear or modify the last error, so its value should be queried only after a confirmed failure.

Related functions and practices

SetLastError can be used to initialize the last-error code for a thread, especially in custom wrappers. In languages and frameworks that use structured exception handling, GetLastError may be used less prominently, but it remains a core part of Windows error reporting for many APIs. Developers should preserve and interpret the value promptly after an API failure to diagnose issues accurately.