ArcObjects error codes

Summary
This topic gives an overview of HRESULTs as they relate to ArcObjects and helps you decipher HRESULT error codes you receive while developing and programming. This topic also shows what an HRESULT is and how to locate information on these error codes in the ArcObjects Software Development Kit (SDK) for the Microsoft .NET Framework. Detailed instructions for the number conversions that are often necessary when working with HRESULTs is also provided.

In this topic

HRESULT error codes

When programming with ArcObjects in .NET, you can make calls to Component Object Model (COM) components and therefore, receive errors from COM components. All COM methods return an unsigned integer (HRESULT).
HRESULT is essentially a structure that shows whether the method succeeded or failed and contains additional detailed information about the outcome of the operation. HRESULT values are often used to return error information that is not specifically considered error codes. The .NET runtime handling of errors from COM components is similar to the way Visual Basic 6 handled COM errors. If a .NET program calls a function in a COM component, and returns an error condition as the HRESULT, the HRESULT is used to populate an instance of the COMException. This exception is thrown by the .NET runtime, where it can be handled by using a Try, Catch, Finally block. For more information on implementing Try, Catch, Finally blocks and the COMException, see How to implement error handling.
Most HRESULT error constants for ArcObjects libraries are documented throughout the ArcObjects .NET SDK help system (see ArcObjects HRESULT error codes in this topic), which is available as part of your SDK installed help or in the ArcObjects namespace reference on the ArcGIS Resource Centers Web site.
HRESULTs that are not specific to ArcObjects can be found on the Microsoft Developer Network (MSDN) Web site. For a list of common MSDN HRESULT values, see Common HRESULT Values on MSDN.
Locating HRESULTs
HRESULTs are returned in an eight-digit hexadecimal form (80004005) or a 10-digit decimal form (–2147467259). The majority of the ESRI ArcObject's error code enumerations are in the 10-digit decimal format.
The following ArcObjects HRESULT error codes table lists all available error enumeration pages and the range of HRESULT values each library contains. If a library is not listed, there are currently no specific HRESULT error codes for that library. Instead, you receive a general COM error. If you have received an eight-digit hexadecimal error code, convert the eight-digit hexadecimal to a 10-digit decimal. This conversion is not difficult and can be accomplished with the Windows Calculator.
Some of the ArcObjects libraries utilize a three-digit value instead of a 10-digit decimal value. These libraries are ESRI.ArcGIS.Geometry (esriGeometryError and esriSpatialReferenceError enumerations) and ESRI.ArcGIS.Geodatabase (esriDataConverterError enumeration). For information on how to convert a 10-digit decimal value to a three-digit enumeration value, see Converting 10-digit decimal value to three-digit enumeration value in this topic.
ArcObjects HRESULT error codes
The following table shows HRESULT error codes for ArcObjects:
Enumeration
Library
Min value
Max value
Geodatabase
513
532
Geometry
513
602
Geometry
514
524
Cadastral
–2147221247
–2147220732
Carto
–2147220991
–2147220989
Carto
–2147220991
–2147220985
Carto
–2147217152
–2147217152
Carto
–2147216896
–2147216895
DataSourcesNetCDF
–2147217408
–2147217401
DataSourcesRaster
–2147217407
–2147217408
DataSourcesRaster
–2147217408
–2147217370
Display
–2147218431
–2147218425
Editor
 –2147220990 –2147220990
GeoAnalyst
–2147217408
–2147217248
Geodatabase
–2147220991
–2147220983
Geodatabase
–2147220991
–2147220879
Geodatabase
–2147220991
–2147212030
Geodatabase
–2147219456
–2147219388
Geodatabase
–2147218687
–2147218670
GeoDatabaseDistributed
–2147208551
–2147208540
GeoDatabaseExtensions
–2147205120
–2147219396
Location
–2147220991
–2147220969
Location
–2147220991
–2147220956
NetworkAnalysis
–2147220911
–2147220225
Output
–2147220735
–2147220719
Output
–2147220686
–2147220670
Schematic
–2147218943
–2147218923
esriSystem
–2147221247
–2147221243
esriSystem
–2147220991
–2147220967
TrackingAnalyst
–2147220480
–2147220352
TrackingAnalyst
–2147219456
–2147219392
TrackingAnalyst
–2147219199
–2147219135

Converting eight-digit hexadecimal value to 10-digit decimal value
Do the following to convert an eight-digit hexadecimal value to a 10-digit decimal value:
  1. Open Windows Calculator. If you do not see the Hex, Dec, Oct, and Bin radio buttons, click View and click Scientific.
  2. Select the Hex and Dword radio buttons.
  3. Ensure the Num Lock is on, and type or paste the eight-digit hexadecimal value in the text field (exclude 0x if it precedes the eight-digit number). See the following screen shot:

  1. Click the Not button.
  2. Click the + button, click the number 1 button, then click the = button to add one.
  3. Click the Bin radio button.
  4. Click the Dec radio button.
  5. Click the +/- button. See the following screen shot:

Converting 10-digit decimal value to three-digit enumeration value
If you have obtained a 10-digit error from the Geometry (esriGeometry and esriSpatialReference) or Geodatabase (esriDataConverter) libraries, do the following steps to obtain the three-digit value from your 10-digit error value.
  1. Access Microsoft's error code lookup utility (ErrLook.exe) with Microsoft Visual Studio by doing one of the following:
    1. In Visual Studio, click Tools, External Tools, and click Add. Click the Ellipsis button and navigate to Program Files\Microsoft Visual Studio 8\Common7\Tools, then click errlook.exe. In the Open File dialog box, click Open. In the External Tools dialog box, add a title for the tool and click OK. The tool now resides under the Tools menu in Visual Studio. 

      -or-
    2. Open Windows Explorer. Navigate to Program Files\Microsoft Visual Studio 8\Common7\Tools to use errlook.exe from this location.
  2. Locate the 10-digit decimal HRESULT you obtained in Step 8 of the preceding section (that is, –2147220984).
  3. Open the ErrLook.exe utility (or access it from the Visual Studio Command Prompt). Type or paste the 10-digit decimal HRESULT referenced in Step 2 in the Value field, including the minus (-) sign in. See the following screen shot:



    Alternatively, open the Visual Studio Command Prompt, type errlook at the prompt, and press Enter to access the Error Lookup utility. See the following screen shot:

  1. Click Lookup in the Error Lookup dialog box to get the converted value and ignore error messages that may be returned, such as No error found. The hexadecimal conversion of your HRESULT appears in the Value field. See the following screen shot:

There is a system error message associated with this HRESULT error code. Although it may be confusing at first, the same error code values can be used across libraries and between systems (that is, Microsoft and ESRI). In this case, you do not want the system error message; instead, you need the ESRI error message.
  1. Open the Windows Calculator and select the Hex radio button. Copy and paste the last three digits (208) from the hexadecimal code you received in the errlook.exe utility. See the following screen shot:

If you do not see the Hex radio button in the Windows Calculator, click the View menu and click Scientific (instead of Standard).
  1. Select the Dec radio button to convert to the three-digit value for the error code. 
  2. Use the three-digit code (520) to find the error on the library documentation page.

Converting error codes without the Error Lookup utility

If you do not have the Error Lookup utility, do the following steps to convert from the 10-digit code to the eight-digit hexadecimal value, then convert to the three-digit decimal value:
  1. Open the Windows Calculator and select the Dec radio button.
  2. Paste the 10-digit code (–2147220984) into the calculator. See the following screen shot:

  1. Click the +/- button to get the positive number.
  2. Select the Bin radio button.
  3. Subtract 1.
  4. Click the Not button (verify the Dword radio button is selected).
  5. Select the Hex radio button to get the hexadecimal form of the error code. See the following screen shot:

  1. With the Hex radio button selected, make note of the last three digits (208) in the number.
  2. With the Hex and Dword radio buttons selected, clear the calculator and add the three digits from Step 8.
  3. Select the Dec radio button to get the three-digit (520) value you need to look up the error code in the documentation. 


See Also:

How to implement error handling
Common HRESULT Values