Convert HRESULT to a human-friendly error (PowerShell)

In several places in Windows (but especially in functions and calls resolving around COM) the errors/warnings returned by Windows APIs are returned as 32-bit numbers HRESULT. The binary value of HRESULT adds a special meaning for certain bits, like information about the type of the error, origin and much more.

Let’s analyze an example value of HRESULT 0x800706BA, which may be also represented in decimal form –2147023174. When seeing that number being returned by the API, it is usually not quite clear what the actual error really is. Wikipedia has a really simple explanation of how the number is structured:

https://en.wikipedia.org/wiki/HRESULT

Based on the specification and a header file to find out the mappings between facilities and their identifiers, I created a simple PowerShell function, which – given a number representing HRESULT – returns a human-friendly structure. This way you can convert this:

0x800706BA 

into this:

HResult : -2147023174
HResultHex : 0x800706BA
HResultBin : 10000000000001110000011010111010
Facility : FACILITY_WIN32
FacilityCode : 7
ErrorCode : 1722
IsFailure : True
Message : RPC server is unavailable
IsCustom : False
IsServerFailure : False 

Much better, isnt’t it? Turns out, this particular HRESULT represents an error, code 1722 (RPC Server is unavailable. Some other information, including representation in different formats are also there.

The usage is simple as that:

 Get-ActualError 0x800706BA 

and the full source code is available in the following gist:

https://gist.github.com/marcinotorowski/8c09fc556469b22a9df421be51e370b2

Leave a Reply