Understanding messages in script tools

When a script is run as a script tool, ArcPy is fully aware of the application it is called from. One major effect of this is that you can write messages with ArcPy and your messages automatically appear on the tool dialog box, in Geoprocessing history, and the Python window. It also means that any model or script tool that calls your script tool has access to the messages you write.

During execution of a tool, messages are written that can be retrieved with geoprocessing functions. These messages include such information as the following:

  • When the operation started and ended
  • The parameter values used
  • General information about the operation's progress (information message)
  • Warnings of potential problems (warning message)
  • Errors that cause the tool to stop execution (error message)

All communication between tools and users is done with messages. Depending on where you are running the tools from, messages appear in the Geoprocessing history, the Python window, and the tool dialog box. From Python, you can fetch these messages within your script, interrogate them, print them, or write them to a file. All messages have a severity property, either informative, warning, or error. The severity is an integer where 0 = informative, 1 = warning, and 2 = error.


Informative message (severity = 0)

An informative message is just that—information about execution. It is never used to indicate problems. Only general information, such as a tool's progress, what time a tool started or completed, output data characteristics, or tool results, is found in informative messages.

Warning message (severity = 1)

Warning messages are generated when a tool experiences a situation that may cause a problem during its execution or when the result may not be what you expect. For example, defining a coordinate system for a dataset that already has a coordinate system defined generates a warning. You can take action when a warning is returned, such as canceling the tool's execution or making another parameter choice.

Error message (severity = 2)

Error messages indicate a critical event that prevented a tool from executing. Errors are generated when one or more parameters have invalid values or when a critical execution process or routine has failed.

Both warning and error messages are accompanied by a six-digit ID code. These ID codes have been documented to provide additional information on their causes and how they can be dealt with. When error or warning codes are shown in the tool dialog box, Python window, or Geoprocessing history, they have a link that allows you to go directly to the additional help for that message.