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 Geoprocessing > Geoprocessing Options and check Log geoprocessing operations to a log file. For more information on activating the log file and how to read it, see History log files.

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
import sys

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))