Troubleshooting
When ATtILA for ArcGIS encounters a potential problem or an unexpected occurrence during the execution of one of its tools, it will attempt to relay that information to the user via the tool's View Details box and the Geoprocessing > History window. Depending on the situation, ATtILA for ArcGIS may provide potential solutions, possible consequences, or some other piece of information deigned useful to the user. In most cases, the message provided in the tool's View Details box and the Geoprocessing > History window will be sufficient to inform the user fully of the situation. In other cases, a more detailed explanation than what can be readily expressed is necessary and a referral to this document is provided.
NOTE: The errors listed below have been encountered over the lifetime of ATtILA's development. While several of them may not still be an issue with the current iteration of ATtILA for ArcGIS Pro, they are included here as a precaution.
Errors encountered:
When running a tool in which the output and intermediate files are directed to be saved to a file geodatabase, the following Background Processing error may occur:
This error may be due to an incompletely deleted file geodatabase, such as the attilaScratchWorkspace.gdb. This occurs periodically when the attilaScratchWorkspace.gdb is deleted using ArcCatalog. While the geodatabase may be successfully deleted and no longer appear in the ArcCatalog interface, some folders and files may linger.
To correct this, simply open Windows Explorer, navigate to the disk location where the file geodatabase formerly resided, and delete the lingering geodatabase folder and its contents.
NOTE: ArcGIS Pro will report 'ERROR 999999: Something unexpected caused the tool to fail.' when ATtILA attempts to write to a corrupted geodatabase. The solution is the same.
SectionThis warning message is triggered when a value is marked as excluded = "true" in the Values Element section of the LCC XML document, but is also included in one or more class definitions in the Classes Element section. The warning message will also provide the class name that contains the value tagged as excluded.
Example:
LCC XML file: excluded value(s) [23] in class DEV definition - Please refer to the ATtILA documentation regarding excluded values.
The value attribute, excluded, (see Values Element in ATtILA's LCC XML Document) is used to identify grid codes whose area is to be excluded from the reporting unit's effective area calculation. Effective area can be thought of as the area of interest within a reporting unit that the user wishes to use for percentage based metric calculations. For example, the user may be interested in basing their metric calculations on just the land area in a reporting unit versus the overall total area of the reporting unit. To make the effective area equal to that of the land area, the user would set the excluded attribute of any water related grid value to "true".
Values attributed as excluded = "true" included in any class definition in the Classes Element section of the LCC XML document create an ambiguous situation for ATtILA for ArcGIS. When this occurs, ATtILA for ArcGIS will ignore the area of that excluded value when summing up the area of the selected class for metric calculations, as well as ignoring its area in the calculation of the effective area.
The following example illustrates the point.
Assume a land cover raster layer contains four land cover types, values 1, 2, 3, and 4 with value 1 attributed as excluded = "true". Only one class has been defined named "Forest", and consists of values 1 and 2. For our example, the different land cover types have the following areas within a reporting unit:
value 1 = 100 square meters
value 2 = 200 square meters
value 3 = 300 square meters
value 4 = 400 square meters
If the Land Cover Proportions tool is run, the output for pForest will be calculated as follows:
pForest = (Area of Forest / Effective Area of Reporting Unit) * 100
If value 1 was not attributed as excluded = "true", then the calculations would be as follows:
pForest = ((Area of value 1 + Area of value 2) / (Area of value 1 +Area of value 2 + Area of value 3 + Area of value 4))
pForest = ((100 sq m + 200 sq m) / (100 sq m + 200 sq m + 300 sq m + 400 sq m)) * 100
pForest = (300 sq m / 1000 sq m) * 100
pForest = 30
But if value 1 is attributed as excluded = "true", then the calculations will adjust to the following:
pForest = ((Area of value 2) / (Area of value 2 + Area of value 3 + Area of value 4))
pForest = ((200 sq m) / (200 sq m + 300 sq m + 400 sq m)) * 100
pForest = (200 sq m / 900 sq m) * 100
pForest = 22.22
NOTE: If all values assigned to the class are tagged as excluded, the output metric is calculated as 0%.
When running a tool that uses a Land cover grid (Core and Edge Metrics, Floodplain Land Cover Proportions, Facility Land Cover Views, Land Cover Coefficient Calculator, Land Cover Diversity Land Cover on Slope Proportions, Land Cover Proportions, Population Land Cover Views, Patch Metrics, Riparian Land Cover Proportions, and Sample Point Land Cover Proportions), an error may occur indicating that TabulateArea failed to execute:
The issue is that raster geoprocessing tools convert other formats to GRID format internally, then perform the analysis, then re-convert the GRID back out to the desired format. The limit is reached at the conversion to the GRID format; GRID's have an upper limit of 2.1 billion cells in their INFO table. The only workaround for this is breaking your data down into smaller chunks before running the tabulate area tool or by selecting a larger processing cell size. The larger processing cell size may allow the process to finish, but the output results will be of a more generalized nature.
This error been detected when executing the Riparian Land Cover Proportions tool. Please report any additional instances of this error to: https://www.epa.gov/enviroatlas/forms/contact-us-about-enviroatlas and include “ATtILA” in the subject line.
This problem appears to occur when the input reporting unit feature consists of a large number of reporting units and/or covers a large geographic area. When the ArcGIS software tries to tile the data to process the dataset, the tiling process appears to fails, usually during the reassembly stage. This is an inconsistent error. Sometimes when the metric run is reattempted, using the exact same inputs, the metric run will finish.
If the metric run fails a second or third time, we recommend using the selection tool and selecting approximately half of the input reporting unit features, exporting the selected reporting units into a new dataset, and reattempting the metric run with the new dataset as the input reporting unit theme.
Continue the reduction process until the metric run runs to completion or until a single reporting unit remains.
If the metric run fails with only one reporting unit feature as the input reporting unit theme, it is likely that there is an error in one of the other input datasets within the confines of the recalcitrant reporting unit. Close inspection of the other input datasets in this area may reveal the problem (e.g. poor digitization of input data as in nodes not being used at line intersections).
When running the Road Density Metrics or the Stream Density Metrics tool, an error may occur indicating that a field already exists:
This error may be caused by problems with the field used to classify the different road or stream features (Road class field or Stream order field, respectively). Specific rules for the length of the fields and the characters contained within the fields are found in each tool's help section.
When running the Road Density Metrics or the Stream Density Metrics tool, an error may occur indicating that a field does not exists:
This error may be caused by problems with the field used to classify the different road or stream features (Road class field or Stream order field, respectively).
If an input feature layer contains a reserved keyword such as ORDER as a field name, that field name is altered slightly by ArcGIS when the input feature layer is copied. ATtILA for ArcGIS copies several of the input feature layers while processing selected metrics. This can result in ATtILA for ArcGIS being unable to located the specified field in the copied dataset. For more guidelines on the naming of fields, search on "Fundamentals of adding and deleting fields" in the ArcGIS help documentation.
When opening ATtILA for ArcGIS"s CHM Help file, one of the following screenshots is displayed:
This error often occurs when the CHM Help file is located on a network drive. To resolve, copy the file onto a local drive and reopen.
If one of ATtILA for ArcGIS's tools 'hangs' (i.e., you enter all the necessary tool inputs and click OK, but the tool never finishes):
-
Open Windows Task Manager and select the hung ArcGIS application in the Applications Tab - Click End Task
-
Reopen the ArcGIS application where the problem occurred
-
Right-click on the tool and open it's properties
-
Check under the source tab to be sure that the 'Run Python script in process' box is checked
That should solve the problem.
To relaunch the tool with all it's previously set parameters, checkboxes, and options, do the following:
- Open the 'Not Run' shortcut menu in the Geoprocessing > Results Window
- Right-click on the tool execution that failed
- Select 'Re-Run'
This error is triggered when ATtILA for ArcGIS is unable to determine the conversion factor necessary to convert output linear units to metric units. The following two possible scenario's have been identified when this may occur.
-
Output Coordinates are not set to a system defined with angular units of Decimal Degrees.
Please be sure that the Environment Settings > Output Coordinates are not set to a system defined with angular units of Decimal Degrees. If an Environment Settings > Output Coordinates is not set, please be sure to select an 'Input reporting unit feature' that does not have a spatial reference defined with angular units of decimal degrees.
-
Output Coordinates unit name is not found in the look up tables used by ATtILA for ArcGIS for metric conversions
It is also possible for this error to occur if the linear units name defined in the Output Coordinates, if one is set, or the linear units property of the 'Input reporting unit feature', if an Output Coordinates is not set, is not found in ATtILA for ArcGIS's look up table for metric conversion factors. Please compare your linear units with those found in the list of Conversion Factors located in the appendix. If the linear units name is not found, it will be necessary to change the Output Coordinates in the Environment Settings to one found in the look table or to project the 'Input reporting unit feature' to a projection with a linear units property known to ATtILA for ArcGIS.
For tools in ATtILA for ArcGIS that utilize an LCC XML document, (i.e., tools that utilize a land cover raster input) ATtILA for ArcGIS will examine all of the values found in that tool's selected land cover raster and compare them to those values supplied in the LCC XML document. The values in the LCC XML document are gathered from both the Values Element section of the document and the Classes Element section. Any values found in the grid but not found in the LCC XML document will be reported to the user with a warning message is added to the tool's View Details box and the Geoprocessing > History window. The user can then determine if the reported values were either accidentally or purposely omitted from the LCC XML document or were possibly incorrectly transcribed. A report of missing values may also indicate that the wrong LCC Schema was selected for the input raster layer, or that the wrong raster layer was input for the selected LCC Schema.
Example:
LCC XML file: grid value(s) [31, 41, 42, 43, 52, 71, 81, 82, 90, 95] undefined in LCC XML file - Please refer to the ATtILA documentation regarding undefined values.
NOTE: Not all values found in the land cover grid need to be included in the LCC XML document. Only land cover values that are of interest to the user (e.g., values for forest or agriculture land cover types) need to be accounted for. If this is the case, and the LCC XML document was constructed to analyze only a subset of land cover classes from the land cover raster, then the warning message from ATtILA from ArcGIS is superfluous and can be ignored.
