How to get the error message from the error code returned by GetLastError

Question

After a Windows API call  how can I get the last error message in a textual form   GetLastError   returns an integer value  not a text message

User · Answer

GetLastError returns a numerical error code. To obtain a descriptive error message (e.g., to display to a user), you can call FormatMessage:

// This functions fills a caller-defined character buffer (pBuffer)
// of max length (cchBufferLength) with the human-readable error message
// for a Win32 error code (dwErrorCode).
// 
// Returns TRUE if successful, or FALSE otherwise.
// If successful, pBuffer is guaranteed to be NUL-terminated.
// On failure, the contents of pBuffer are undefined.
BOOL GetErrorMessage(DWORD dwErrorCode, LPTSTR pBuffer, DWORD cchBufferLength)
{
    if (cchBufferLength == 0)
    {
        return FALSE;
    }

    DWORD cchMsg = FormatMessage(FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS,
                                 NULL,  /* (not used with FORMAT_MESSAGE_FROM_SYSTEM) */
                                 dwErrorCode,
                                 MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
                                 pBuffer,
                                 cchBufferLength,
                                 NULL);
    return (cchMsg > 0);
}

In C++, you can simplify the interface considerably by using the std::string class:

#include <Windows.h>
#include <system_error>
#include <memory>
#include <string>
typedef std::basic_string<TCHAR> String;

String GetErrorMessage(DWORD dwErrorCode)
{
    LPTSTR psz{ nullptr };
    const DWORD cchMsg = FormatMessage(FORMAT_MESSAGE_FROM_SYSTEM
                                         | FORMAT_MESSAGE_IGNORE_INSERTS
                                         | FORMAT_MESSAGE_ALLOCATE_BUFFER,
                                       NULL, // (not used with FORMAT_MESSAGE_FROM_SYSTEM)
                                       dwErrorCode,
                                       MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
                                       reinterpret_cast<LPTSTR>(&psz),
                                       0,
                                       NULL);
    if (cchMsg > 0)
    {
        // Assign buffer to smart pointer with custom deleter so that memory gets released
        // in case String's c'tor throws an exception.
        auto deleter = [](void* p) { ::LocalFree(p); };
        std::unique_ptr<TCHAR, decltype(deleter)> ptrBuffer(psz, deleter);
        return String(ptrBuffer.get(), cchMsg);
    }
    else
    {
        auto error_code{ ::GetLastError() };
        throw std::system_error( error_code, std::system_category(),
                                 "Failed to retrieve error message string.");
    }
}

NOTE: These functions also work for HRESULT values. Just change the first parameter from DWORD dwErrorCode to HRESULT hResult. The rest of the code can remain unchanged.

These implementations provide the following improvements over the existing answers:

Complete sample code, not just a reference to the API to call.
Provides both C and C++ implementations.
Works for both Unicode and MBCS project settings.
Takes the error code as an input parameter. This is important, as a thread's last error code is only valid at well defined points. An input parameter allows the caller to follow the documented contract.
Implements proper exception safety. Unlike all of the other solutions that implicitly use exceptions, this implementation will not leak memory in case an exception is thrown while constructing the return value.
Proper use of the FORMAT_MESSAGE_IGNORE_INSERTS flag. See The importance of the FORMAT_MESSAGE_IGNORE_INSERTS flag for more information.
Proper error handling/error reporting, unlike some of the other answers, that silently ignore errors.

This answer has been incorporated from Stack Overflow Documentation. The following users have contributed to the example: stackptr, Ajay, Cody Gray?, IInspectable.

User · Answer

FormatMessage will turn GetLastError s integer return into a text message

User · Answer

MSDN has some sample code that demonstrates how to use FormatMessage   and GetLastError   together  Retrieving the Last-Error Code

User · Answer

void WinErrorCodeToString DWORD ErrorCode  string amp  Message    char  locbuffer   NULL  DWORD count   FormatMessageA FORMAT MESSAGE FROM SYSTEM   FORMAT MESSAGE ALLOCATE BUFFER  NULL  ErrorCode      0   LPSTR  amp locbuffer  0  nullptr   if  locbuffer        if  count                int c          int back   0                        strip any trailing   r n s and replace by a single   n                     while    c    CharPrevA locbuffer  locbuffer   count        r                   c      n                  count--              back                       if  back                locbuffer count        n               locbuffer count      0                      Message    Error             Message    locbuffer            LocalFree locbuffer     else       Message    Unknown error code      to string ErrorCode

User · Answer

i ll leave this here since i will need to use it later  It s a source for a small binary compatible tool that will work equally well in assembly  C and C     GetErrorMessageLib c  compiled to GetErrorMessageLib dll    include  lt Windows h gt           returns 0 if there was enough space  size of buffer in bytes needed    to fit the result  if there wasn t enough space  -1 on error        declspec dllexport  int GetErrorMessageA DWORD dwErrorCode  LPSTR lpResult  DWORD dwBytes            LPSTR tmp      DWORD result len       result len   FormatMessageA           FORMAT MESSAGE FROM SYSTEM   FORMAT MESSAGE IGNORE INSERTS   FORMAT MESSAGE ALLOCATE BUFFER          NULL          dwErrorCode          LANG SYSTEM DEFAULT           LPSTR  amp tmp          0          NULL                     if  result len    0            return -1                FormatMessage s return is 1 character too short        result len       strncpy lpResult  tmp  dwBytes        lpResult dwBytes - 1    0      LocalFree  HLOCAL tmp        if  result len  lt   dwBytes            return 0        else           return result len                   returns 0 if there was enough space  size of buffer in bytes needed    to fit the result  if there wasn t enough space  -1 on error        declspec dllexport  int GetErrorMessageW DWORD dwErrorCode  LPWSTR lpResult  DWORD dwBytes           LPWSTR tmp      DWORD nchars      DWORD result bytes       nchars   dwBytes  gt  gt  1       result bytes   2   FormatMessageW           FORMAT MESSAGE FROM SYSTEM   FORMAT MESSAGE IGNORE INSERTS   FORMAT MESSAGE ALLOCATE BUFFER          NULL          dwErrorCode          LANG SYSTEM DEFAULT           LPWSTR  amp tmp          0          NULL                 if  result bytes    0            return -1                 FormatMessage s return is 1 character too short      result bytes    2       wcsncpy lpResult  tmp  nchars       lpResult nchars - 1    0      LocalFree  HLOCAL tmp        if  result bytes  lt   dwBytes            return 0        else           return result bytes   2            inline version GetErrorMessage h     ifndef GetErrorMessage H   define GetErrorMessage H   include  lt Windows h gt               returns 0 if there was enough space  size of buffer in bytes needed    to fit the result  if there wasn t enough space  -1 on error      static inline int GetErrorMessageA DWORD dwErrorCode  LPSTR lpResult  DWORD dwBytes            LPSTR tmp      DWORD result len       result len   FormatMessageA           FORMAT MESSAGE FROM SYSTEM   FORMAT MESSAGE IGNORE INSERTS   FORMAT MESSAGE ALLOCATE BUFFER          NULL          dwErrorCode          LANG SYSTEM DEFAULT           LPSTR  amp tmp          0          NULL                     if  result len    0            return -1                FormatMessage s return is 1 character too short        result len       strncpy lpResult  tmp  dwBytes        lpResult dwBytes - 1    0      LocalFree  HLOCAL tmp        if  result len  lt   dwBytes            return 0        else           return result len                   returns 0 if there was enough space  size of buffer in bytes needed    to fit the result  if there wasn t enough space  -1 on error      static inline int GetErrorMessageW DWORD dwErrorCode  LPWSTR lpResult  DWORD dwBytes           LPWSTR tmp      DWORD nchars      DWORD result bytes       nchars   dwBytes  gt  gt  1       result bytes   2   FormatMessageW           FORMAT MESSAGE FROM SYSTEM   FORMAT MESSAGE IGNORE INSERTS   FORMAT MESSAGE ALLOCATE BUFFER          NULL          dwErrorCode          LANG SYSTEM DEFAULT           LPWSTR  amp tmp          0          NULL                 if  result bytes    0            return -1                 FormatMessage s return is 1 character too short      result bytes    2       wcsncpy lpResult  tmp  nchars       lpResult nchars - 1    0      LocalFree  HLOCAL tmp        if  result bytes  lt   dwBytes            return 0        else           return result bytes   2            endif    GetErrorMessage H      dynamic usecase assumed that error code is valid  otherwise a -1 check is needed     include  lt Windows h gt   include  lt Winbase h gt   include  lt assert h gt   include  lt stdio h gt   int main int argc  char   argv           int   GetErrorMessageA  DWORD  LPSTR  DWORD       int   GetErrorMessageW  DWORD  LPWSTR  DWORD       char result1 260       wchar t result2 260        assert LoadLibraryA  GetErrorMessageLib dll          GetErrorMessageA    int     DWORD  LPSTR  DWORD  GetProcAddress           GetModuleHandle  GetErrorMessageLib dll             GetErrorMessageA                     GetErrorMessageW    int     DWORD  LPWSTR  DWORD  GetProcAddress           GetModuleHandle  GetErrorMessageLib dll             GetErrorMessageW                      GetErrorMessageA 33  result1  sizeof result1        GetErrorMessageW 33  result2  sizeof result2         puts result1        putws result2        return 0      regular use case assumes error code is valid  otherwise -1 return check is needed     include  lt stdio h gt   include  GetErrorMessage h   include  lt stdio h gt   int main int argc  char   argv        char result1 260       wchar t result2 260        GetErrorMessageA 33  result1  sizeof result1        puts result1        GetErrorMessageW 33  result2  sizeof result2         putws result2        return 0      example using with assembly gnu as in MinGW32 again  assumed that error code is valid  otherwise -1 check is needed         global  WinMain 16       section  text  WinMain 16         eax   LoadLibraryA  GetErrorMessageLib dll       push  sz0     call  LoadLibraryA 4    stdcall  no cleanup needed         eax   GetProcAddress eax   GetErrorMessageW       push  sz1     push  eax     call  GetProcAddress 8    stdcall  no cleanup needed           eax  errorCode  szErrorMessage      push  200     push  szErrorMessage     push errorCode            call   eax    cdecl  cleanup needed     add  12   esp      push  szErrorMessage     call   putws    cdecl  cleanup needed     add  4   esp      ret  16       section  rodata sz0   asciz  GetErrorMessageLib dll      sz1   asciz  GetErrorMessageW  errorCode   long 33       section  data szErrorMessage   space 200   result  The process cannot access the file because another process has locked a portion of the file

User · Answer

In general  you need to use FormatMessage to convert from a Win32 error code to text   From the MSDN documentation      Formats a message string  The function   requires a message definition as   input  The message definition can come   from a buffer passed into the   function  It can come from a message   table resource in an already-loaded   module  Or the caller can ask the   function to search the system s   message table resource s  for the   message definition  The function finds   the message definition in a message   table resource based on a message   identifier and a language identifier    The function copies the formatted   message text to an output buffer    processing any embedded insert   sequences if requested    The declaration of FormatMessage   DWORD WINAPI FormatMessage      in      DWORD dwFlags      in opt  LPCVOID lpSource      in      DWORD dwMessageId     your error code     in      DWORD dwLanguageId      out     LPTSTR lpBuffer      in      DWORD nSize      in opt  va list  Arguments

User · Answer

Since c  11  you can use the standard library instead of FormatMessage    include  lt system error gt   std  string GetLastErrorAsString        DWORD errorMessageID     GetLastError        if  errorMessageID    0            return std  string      No error message has been recorded       else           return std  system category   message errorMessageID

User · Answer

If you need to support MBCS as well as Unicode  Mr C64 s answer is not quite enough  The buffer must be declared TCHAR  and cast to LPTSTR  Note that this code doesn t deal with the annoying newline that Microsoft appends to the error message   CString FormatErrorMessage DWORD ErrorCode        TCHAR    pMsgBuf   NULL      DWORD   nMsgLen   FormatMessage FORMAT MESSAGE ALLOCATE BUFFER           FORMAT MESSAGE FROM SYSTEM   FORMAT MESSAGE IGNORE INSERTS          NULL  ErrorCode  MAKELANGID LANG NEUTRAL  SUBLANG DEFAULT           reinterpret cast lt LPTSTR gt   amp pMsgBuf   0  NULL       if   nMsgLen          return  T  FormatMessage fail        CString sMsg pMsgBuf  nMsgLen       LocalFree pMsgBuf       return sMsg      Also  for brevity I find the following method useful   CString GetLastErrorString         return FormatErrorMessage GetLastError

User · Answer

If you re using c  you can use this code   using System Runtime InteropServices   public static class WinErrors        region definitions      DllImport  kernel32 dll   SetLastError   true       static extern IntPtr LocalFree IntPtr hMem         DllImport  kernel32 dll   SetLastError   true       static extern int FormatMessage FormatMessageFlags dwFlags  IntPtr lpSource  uint dwMessageId  uint dwLanguageId  ref IntPtr lpBuffer  uint nSize  IntPtr Arguments         Flags      private enum FormatMessageFlags   uint               FORMAT MESSAGE ALLOCATE BUFFER   0x00000100          FORMAT MESSAGE IGNORE INSERTS   0x00000200          FORMAT MESSAGE FROM SYSTEM   0x00001000          FORMAT MESSAGE ARGUMENT ARRAY   0x00002000          FORMAT MESSAGE FROM HMODULE   0x00000800          FORMAT MESSAGE FROM STRING   0x00000400             endregion           lt summary gt          Gets a user friendly string message for a system error code          lt  summary gt           lt param name  errorCode  gt System error code lt  param gt           lt returns gt Error string lt  returns gt      public static string GetSystemMessage int errorCode                try                       IntPtr lpMsgBuf   IntPtr Zero               int dwChars   FormatMessage                  FormatMessageFlags FORMAT MESSAGE ALLOCATE BUFFER   FormatMessageFlags FORMAT MESSAGE FROM SYSTEM   FormatMessageFlags FORMAT MESSAGE IGNORE INSERTS                  IntPtr Zero                   uint  errorCode                  0     Default language                 ref lpMsgBuf                  0                  IntPtr Zero               if  dwChars    0                                   Handle the error                  int le   Marshal GetLastWin32Error                    return  Unable to get error code string from System - Error     le ToString                               string sRet   Marshal PtrToStringAnsi lpMsgBuf                   Free the buffer              lpMsgBuf   LocalFree lpMsgBuf               return sRet                    catch  Exception e                        return  Unable to get error code string from System - gt      e ToString

User · Answer

Updated  11 2017  to take into consideration some comments   Easy example   wchar t buf 256   FormatMessageW FORMAT MESSAGE FROM SYSTEM   FORMAT MESSAGE IGNORE INSERTS                 NULL  GetLastError    MAKELANGID LANG NEUTRAL  SUBLANG DEFAULT                   buf   sizeof buf    sizeof wchar t    NULL

User · Answer

Returns the last Win32 error  in string format  Returns an empty string if there is no error  std  string GetLastErrorAsString           Get the error message ID  if any      DWORD errorMessageID     GetLastError        if errorMessageID    0            return std  string      No error message has been recorded                LPSTR messageBuffer   nullptr         Ask Win32 to give us the string version of that message ID        The parameters we pass in  tell Win32 to create the buffer that holds the message for us  because we don t yet know how long the message string will be       size t size   FormatMessageA FORMAT MESSAGE ALLOCATE BUFFER   FORMAT MESSAGE FROM SYSTEM   FORMAT MESSAGE IGNORE INSERTS                                   NULL  errorMessageID  MAKELANGID LANG NEUTRAL  SUBLANG DEFAULT    LPSTR  amp messageBuffer  0  NULL              Copy the error message into a std  string      std  string message messageBuffer  size              Free the Win32 s string s buffer      LocalFree messageBuffer                    return message

[c++] How to get the error message from the error code returned by GetLastError()?

Examples related to c++

Examples related to c

Examples related to winapi