Troubleshooting geoprocessing REST services

The most common problems with a geoprocessing service can be discovered using one or more of these techniques:

• Enable geoprocessing messages on the service, rerun the task, and inspect the messages.
• Run the task and Inspect the arcgisjobs directory.
• Verify that the transfer limit property has not been exceeded.

You can edit the geoprocessing properties discussed below using ArcMap or ArcGIS Server Manager.

Enabling info-level geoprocessing messages

Geoprocessing tool messages contain a detailed step-by-step account of the execution of a geoprocessing task. In case of failure, the geoprocessing messages will help you identify the exact point of failure of a geoprocessing task. The geoprocessing messages sent to the client is determined by the Message Level property of the geoprocessing service. The four levels of messages are None, Error, Warning, and Info. If the message level is set to None, the Execute Task or Submit Job operation of the geoprocessing task will not return any geoprocessing tool messages other than success or failure of the task. The Info level provides all geoprocessing messages that are generated by the task and is recommended for troubleshooting. You can set the Message Level property of the geoprocessing service to Info level through ArcGIS Server Manager or ArcMap and troubleshoot further.

Tip:

If you did not receive any geoprocessing messages even after setting your message level to Info, it indicates invalid inputs. The input parameter values of the task may be malformed, partial, or invalid JSONs. You must verify the input parameter data types and their JSON values.

Inspecting the arcgisjobs directory

Another way to troubleshoot geoprocessing services is to use asynchronous execution mode for debugging. You can edit the execution mode property of the geoprocessing service through ArcGIS Server Manager or ArcMap. In asynchronous execution mode, the server creates a unique directory for every job submitted by its client in the arcgisjobs directory. Each directory will have a scratch folder that serves as a scratch workspace for the geoprocessing job running at server. The output data, intermediate (scratch) data, and geoprocessing messages generated by the asynchronous job are written to the scratch workspace. You can examine the data in the scratch workspace to identify problems and issues that may have caused the task to fail.

The arcgisjobs directory is a configurable property of a geoprocessing service and can be modified during publishing or later. The default path to arcgisjobs directory is <server_directories>\directories\arcgisjobs. The default scratch workspace of an asynchronous job will be <arcgis-jobs-folder>\<server_folder_if_any>\<gpservice_name>\<jobid>\scratch.

Contents of a server scratch workspace

• scratch folder—The scratch folder will have file-based output data such as shapefiles, rasters, and so forth, depending on the functionality of the tool.
• scratch.gdb—The scratch.gdb geodatabase resides within the scratch folder, and output datasets such as feature classes and geodatabase rasters will be written to the scratch.gdb geodatabase.
• messages.xml—The message.xml file resides within the scratch folder and will have all the geoprocessing messages that were logged for geoprocessing tasks. The messages in the XML file are dependent on the Message Level property of the geoprocessing service.

Tip:

The scratch directories in the arcgisjobs folder will be deleted at predefined intervals as part of the server’s cleanup routine. The duration of cleanup is determined by the Maximum File Age property of the arcgisjobs directory. The default value is 360 minutes but can be modified by the server administrator using ArcMap or ArcGIS Server Manager.

Tip:

The server writes intermediate data generated by the model or script to the scratch folder during task execution. However, the intermediate data will be deleted at the end of execution. If you wish to inspect a specific intermediate data in your model or script, convert them to output parameters in your model or script, create a new result, and publish the result as a service. Execute this new service to examine the new output data.

Exceeding the transfer limit

Sometimes, your synchronous or asynchronous task may succeed, but the output feature set or record set parameters returned by the server may not have any features or records. In such cases, you must increase the value of Maximum number of records returned by the server property of the geoprocessing service in ArcMap or ArcGIS Server Manager. The maximum number of output features and records returned by a geoprocessing task is determined by the Maximum number of records returned by the server property. The default value of the property is 1,000 records or features. When the number of records or features of a task output is greater than the Maximum number of records returned by the server property, the geoprocessing task will not return any records or features even though the task succeeded.