Understanding geoprocessing tool errors and warnings

Geoprocessing errors and warnings are returned from geoprocessing tools with a six-digit code and a text message. Every error and warning has a corresponding description page in the desktop help system. This page contains both a detailed description of the error and possible solutions for the error. In tool dialog boxes, the Python window, and the Results window, the ID code is a link that, when clicked, takes you to a description page.

Internal errors and history log files

When a tool generates an error, a standard error code and message are displayed. In some cases, there may be internal system errors that accompany the standard error code. These internal system errors are not typically provided as part of the standard error message as they tend to provide minimal help in understanding the problem. However, in certain cases, these messages may provide additional leads to correcting and dealing with the cause of the error.

To view any internal system errors, you must first enable message logging. Click the Project tab, in the Options panel, click Geoprocessing, then check Write geoprocessing operations to XML log file. For more information on activating the log file, see Write geoprocessing operations to XML log file.

Writing standard errors and warnings in scripts and script tools

In Python, you have the ability to write your own custom errors and warnings using the AddWarning and AddError functions. But you can also write any of the standard error or warning messages using the AddIDMessage function. By writing a standard error or warning, you free yourself from providing your own documentation—users of your scripts can read the error descriptions and solutions found in the desktop help.

To write a standard error or warning, you must first know the six-digit code. This will require some research on your part; you will have to search the descriptions found in the desktop help to find the right six-digit code. Once you've identified an appropriate code, make note of any additional information that needs to be included in the message, usually referenced as <value>. For example, code 12 is "<value> already exists." In this case, you will need to provide a value (that is, the name of the dataset) to the {add_argument1} parameter of AddIDMessage().

The Python sample below checks to see whether a feature class has been provided as input and, if not, uses the AddIDMessage() to return code 12 (000012: <value> already exists). The optional argument is used to substitute the feature class name into the message.

class overwriteError(Exception):
    pass

import arcpy

inFeatureClass  = arcpy.GetParameterAsText(0)
outFeatureClass = arcpy.GetParameterAsText(1)

try:
    # If the output feature class already exists, raise an error
    if arcpy.Exists(inFeatureClass):
        raise overwriteError(outFeatureClass)
    else:
        # Additional processing steps

except overwriteError as e:
    # Use message ID 12, and provide the output feature class
    #    to complete the message.
    arcpy.AddIDMessage("Error", 12, str(e))