A Non-programmer's Guide to Troubleshooting ArcPy

AndrewOrtego · ‎03-07-2016

My name is Andrew--you can call me Drew--and I’m a Desktop Support Analyst with Esri Support Services. If you’ve ever called us to talk about a Python issue, you’ve probably spoken to me! I get a lot of positive feedback from the people I speak with about troubleshooting Python scripts, and I’d like to share the most popular advice I have to give. Whether you’re learning to code for the first time, or just getting started with the ArcPy site package, these tips and tricks should help you get your script back on track and closer to completion.

Since we get a lot of different Python-related calls in Support, I’ve collected the six most common requests into the scenarios below. Use these scenarios to help you decide which workflow applies to your current problem.1. You’re getting started with Python for the first time and aren't sure how to start learning it.

You’re in luck! I wrote a blog about this very problem about a year ago! That blog contains tutorials that help anyone learn to code in Python and links to many free online resources--these resources are organized by learning styles, so there’s something for everyone.Seven easy ways to start learning Python and ArcPy2. Your script returns the error message: “ImportError: No module named arcpy."

This is the most frequent issue Esri Support encounters when troubleshooting ArcPy. The error message is produced when the ArcPy site package is installed incorrectly, but it’s very easy to fix. There are a number of causes that can interplay to produce this error, so it is best to refer to Knowledge Base article 43846, Problem: Unable to import arcpy, for more details when troubleshooting this type of issue.

If that article doesn’t provide a solution, I recommend speaking with your IT team to determine if there’s any reason to expect that you wouldn’t have full read or write permissions to the directories you’re accessing. If you’re working on a remote machine, attempt to troubleshoot directly on the machine installed with ArcGIS for Desktop.3. The script you wrote works everywhere except in the Windows Task Scheduler.

Since Esri didn’t create the Windows Task Scheduler (WTS), this is a tricky one to troubleshoot with Esri Support. However, the Knowledge Base article, Windows Task Scheduler will not run a Python script, will help you verify whether the issue is with the WTS, the Python installation, or your script.4. You want to start creating a script, or you have started creating a script and need to move forward, but are getting stuck.

In this case, you’ve got a goal in mind, you can make it work without Python, but you need to code. Where do you go? The most important step is verifying that you have a desirable outcome in mind. With a goal in mind, you can break your problem down into logical steps.

For example, let’s say you want to write a script that will clip one feature to another. First, try it in ArcMap. Does your data give you the expected results? Are you positive that this is the workflow you need? If so, then it’s time to review the documentation for the Clip tool and get the Python syntax that helps you do this. Check out the ArcGIS for Desktop Help page for this information, conveniently found here:Clip Tool Reference

Notice that the Syntax section tells you the name of the ArcPy function associated with the Geoprocessing tool, as well as the parameters needed (plus optional parameters) to make the function run properly. Keep an eye on those data types-- they can be tricky sometimes!

The Code Sample section is very useful for those of us who like to learn by example, so take a look at that section before you start coding; it may help demonstrate how to use the function even better than the Syntax section.5. Your script is not producing the expected results, and/or you suspect an ArcPy function is causing a problem.

I see this problem all the time, and I’ve come up with a solution that never fails to solve it. The following steps should help you learn more about the source of the issue.a. Whether you’re getting an error message, or your output is incorrect, you’ll benefit from isolating the code that is causing a problem. Make a script that demonstrates the “smallest testable case”.b. Troubleshooting a single ArcPy function is a lot easier than troubleshooting a 2,000-line script. Put the suspected function into its own .py file (and maybe even create some small test data), and verify that you’re getting the expected output from that function.c. Add some other code, if needed, but don’t forget that the purpose of this test is to isolate the issue down to a single line in your larger script. Any problem can be simplified, and taking a step back, instead of pushing forward, will save you a lot of debug time.6. Your code is not working, and you feel comfortable using Python to isolate the issue.

Here are some more advanced tips for troubleshooting your script:a. Test the function both in and out of the ArcMap or ArcCatalog Python console. This will indicate whether or not an integrated development environment (IDE) is properly accessing the Python.exe file installed with ArcGIS for Desktop. ArcMap and ArcCatalog should always be able to run ArcPy functions. If these programs cannot run ArcPy functions, a reinstallation might be necessary.b. Test the function with different data. This indicates whether the issue is data-specific or not.c. Check the online documentation specific to the version of ArcGIS for Desktop you are using. With each new release, some updates are made to the ArcPy site package that change the behavior of ArcPy’s functions.d. If you suspect that a function is incorrectly written, run the function in ArcMap or ArcCatalog, and use the Geoprocessing Results window to copy the Python version of that geoprocessing tool into the Windows Clipboard. Paste the results into your favorite IDE, and compare your code to the Esri-made Python snippet. It might be a little messier than your code, but comparing the two could give you a hint as to where the problem can be found.

I hope that helps! Remember, coding is a skill, and it can be really confusing sometimes. Be patient with yourself, and you’ll soon have all these troubleshooting steps integrated into each script-writing session you embark upon. Don’t be afraid to search the internet for solutions that others have come up with, and of course, feel free to give us a call here at Esri Support if you are current on maintenance. Good luck, and happy coding!

Andrew O. - Desktop Support Analyst