Message types and severity

When a tool is run, messages are written that can be retrieved with geoprocessing functions, such as GetMessages and GetAllMessages. 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 running (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 Result window, the Python window, and the progress 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.

SeverityDescription

Informative message (severity = 0)

An informative message is information about a tool run. 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 when the tool is running 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 returns, such as canceling the tool's run or making another parameter choice.

Error message (severity = 2)

Error messages indicate a critical event that prevented a tool from running. Errors are generated when one or more parameters have invalid values, or when a critical 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 or progress dialog box, Python window, or Result window, they have a link that allows you to go directly to the additional help for that message.

Access messages

Messages from the last tool run can be retrieved using the GetMessages or GetAllMessages functions.

The GetMessages function returns a single string containing all the messages from the tool that was previously run. The returned messages can be filtered to include only those with a certain severity using the severity option. The tool's first and last messages always give the start and end time, respectively, for the running of the tool.

Accessing geoprocessing messages with GetMessages

import arcpy

# Run the GetCount tool
arcpy.management.GetCount("c:/base/data.gdb/roads") 

# Get the resulting messages and print them
print(arcpy.GetMessages())

The GetAllMessages function returns a list of lists containing the message type, return codes, and message strings for all messages from the tool that was previously run. The tool's first and last messages always give the start and end time, respectively, for the running of the tool.

Accessing geoprocessing messages with GetAllMessages

import arcpy
from pprint import pprint

# Run the GetCount tool
arcpy.management.GetCount("c:/base/data.gdb/roads") 

# Get the resulting messages and print them
pprint(arcpy.GetAllMessages())

Individual messages can be retrieved using the GetMessage function. This function has one parameter, which is the index position of the message. The GetMessageCount function returns the number of messages from the previously run tool. The example below shows how to print information about the start and end times for the tool.

import arcpy

arcpy.env.workspace = "D:/base/data.gdb"

arcpy.analysis.Clip("roads", "urban_area", "urban_roads")

# Print the first message
print(arcpy.GetMessage(0))

# Print the last message - ending and elapsed times for tool
print(arcpy.GetMessage(arcpy.GetMessageCount - 1))

Access messages from a Result object

Messages can also be accessed from a tool using a Result object. Messages on a Result object can be maintained even after running multiple tools. The Result object supports several of the same functions used to get and interpret geoprocessing tool messages.

Result properties and methods

Properties and methodsExplanation

inputCount

Returns the number of inputs.

outputCount

Returns the number of outputs.

messageCount

Returns the number of messages.

maxSeverity

Returns the maximum severity. The returned severity can be 0 (no errors/warnings raised), 1 (warnings raised), or 2 (errors raised).

resultID

Returns the unique result ID. If the tool is not a geoprocessing service, the resultID will be "".

status

Returns the status of the job on the server.

  • 0—New
  • 1—Submitted
  • 2—Waiting
  • 3—Running
  • 4—Succeeded
  • 5—Failed
  • 6—Timed Out
  • 7—Canceling
  • 8—Canceled
  • 9—Deleting
  • 10—Deleted

cancel()

Cancels the job on the server.

getAllMessages()

Returns the message types, return codes, and message strings.

getInput(index)

Returns a given input. If a record set or raster data object, a RecordSet or RasterData object is returned.

getMapImageURL(parameter_list, height, width, resolution)

Gets map service image for a given output.

getMessage(index)

Returns a specific message by index.

getMessages(severity)

Returns the geoprocessing tool messages. A severity value can be expressed as 0 (informative), 1 (warning), or 2 (error). Not specifying a severity value returns all message types.

getOutput(index)

Returns a given output. If a record set or raster data object, a RecordSet, or RasterData object is returned.

getSeverity(index)

Returns the severity of a specific message.

Result properties and methods

The following sample runs two geoprocessing tools but waits until the tools are run before reviewing the messages.


import arcpy

arcpy.env.workspace = "D:/base/data.gdb"

# Run the Clip and GetCount tools
clipResult = arcpy.analysis.Clip("roads", "urban_area", "urban_roads")
countResult = arcpy.management.GetCount("urban_roads")

# Get the resulting messages and print them
print(clipResult.getMessages())
print(countResult.getMessages())

As with geoprocessing tools, server tool messages are classified as information, a warning, or an error. A message's type is indicated by its severity property, which is a numeric value. The following sample shows how to get the messages from a server tool after it has completed.


import arcpy
import time

# Add the server toolbox
arcpy.ImportToolbox("http://lab13/arcgis/services;BufferByVal", "mytools")

featset = arcpy.FeatureSet()
featset.load("//flames/gpqa/coredata/global/redlands/control.shp")

# Run a server tool named BufferPoints
result = arcpy.mytools.BufferPoints(featset, "1000 feet")

# Wait until the tool completes
while result.status < 4:
    time.sleep(0.2)

# Print all messages from the result object
print(result.getMessages())