Engine Works
Under the hood of Alteryx: tips, tricks and how-tos.
'The external program "<name>" returned an error code: 1'
words which chill our very souls. We know something's gone wrong, but we've got nothing to go on. If we see this message when running something on the Alteryx Gallery then we've got a very long, frustrating call ahead of us with the Server admin trying to work out what exactly is happening. It's at this point most people look at the rest of their to-do list and pick something else to work on.
Well no more. In this blog, I'm going to show 3 tips that can make it way more possible to debug failing scripts being run in Alteryx.
So here I've got a simple workflow where I create a .hyper file locally, then create and run a tabcmd script to publish that file to my Tableau server.
But something is wrong. I can see error code 1, but if I run the workflow locally, the terminal window disappears before I've got a hope of reading what it's saying, and if I'm running this on gallery I never even see the window.
So what can I do?
WARNING
The approach I'm about to show involves writing and reading log files in plain text. These logs could (depending on your scripts) include sensitive information such as credentials/passwords.
This approach may therefore be unsuitable for you and is mostly presented as a debugging technique, rather than as a way to build production workflows.
Logs aren't just for lumberjacks
The first thing we can do is write out a file explaining what is going on. We can output both what the command we've actually written is, but also any error messages that those commands create.
This is how I've configured my run command tool currently:
I'm writing out a batch script called tabout.bat, and then running that script as my command.
I can log what's going on by adding some command arguments:
tabout.bat > testlog.txt 2>&1
This little snippet of code has 2 parts:
Firstly,
tabout.bat > testlog.txtoutputs the tabout.bat file as a new file called testlog.txt, in the directory the command is currently running from.
Secondly,
2>&1 takes all messages (including errors) that were written to the terminal, and outputs them appended to the testlog.txt file we've just created.
If we have a look at the testlog.txt we get a much better idea of what's going on (or wrong in this case).
Writing out a log file is (as we see) incredibly useful. If we run this workflow on Gallery though, we probably won't have access to the logfile location. If we don't use a relative filepath, then there's a possibility that there is no location that both we and the server machine can access.
Because of this, I sometimes like to read in the log files into the same workflow, and (optionally) display them in the workflow messages.
This way all files (.bat or logs) are written to the server temp directory which is cleared after the workflow has run.
So here I've attached a final control container which will run after the run command tool has finished.
This container reads in the testlog.txt file that's just been written (as an undelimited .csv) and then displays this information using the API Output tool.
This isn't a common tool but simply turns any data fed into it as a message displayed in the results window, or workflow results on Gallery.
This means that we can read the contents of the testlog file even if we can't access the physical location of the file.
Here we can see how that looks in the results window:
and here's what it looks like when run from Gallery (where it's not my PAT that's the issue, but rather the lack of tabcmd being installed).
Not the nicest way to read the information, but it is at least accessible now.
Is there an echo in here?
The blog could end here, as I've shown a way to debug that awful error code. But with more complex scripts, poring through the logs can be difficult. My final tip is to make your own life easier, by signposting the different parts of the script using ECHO.
Here is the now corrected .bat file I wrote with my workflow:
tabcmd login --server https://<server>.co.uk --site <site> --token-name <PATName> --token-value <PATValue>
tabcmd publish -o test.hyper --name "tabcmdtest" --project "OllieTabcmdTesting"
We can 'annotate' it using echo statements like this:
echo attempting to login
tabcmd login --server https://<server>.co.uk --site <site> --token-name <PATName> --token-value <PATValue>
echo login step completed
echo attempting to publish
tabcmd publish -o test.hyper --name "tabcmdtest" --project "OllieTabcmdTesting"
echo publishing completed
These simply print our echo statement to the terminal (and to our logfile), which can help workout exactly where in our script the error is occurring.
I like to wrap each section of the script with an echo before saying what's about to happen and one after saying what has just happened.
This can be done pretty straightforwardly in a formula tool by concatenating strings together.
Echo statements in the log file
So that's my approach to debugging run command errors. I've found it incredibly useful in the past, and it's saved me hours of calls with IT. It does however have infosec considerations, so whether it's the right approach for you depends on your scripts.
Either way, I hope you found this useful and/or interesting.
If you've got any questions, then you can always find me on the Maveryx Community, LinkedIn or Twitter.
This blog was originally published on theinformationlab.co.uk
