Templater writes a failure down in a fixed shape: one error object, on one line, in a file named templater.err, with a numeric code you can feed back into the options file to stop the whole run on the first time that code appears. Once you can read that object, you can answer “what went wrong” and “should this batch have kept going” from the file itself, without watching the screen.
This page is about the files and the code, not about a particular failure. If you want a list of symptoms with fixes, our page of Templater problems and fixes is organized that way, and our look at what happens when a batch fails mid-queue covers the Bot and its status column. Here we take one error object apart, field by field, and then use its code to decide when a run should halt.
Three files, three jobs
When Templater runs from the command line, it leaves a trail in three files. Our troubleshooting page names them and says where they live: in the directory you set with the log_location key in templater-options.json. Two of the three are written by the logging system and one is written when something goes wrong.
templater.log holds messages. It is the file to open in an ordinary text editor, and it is the one to share when you ask someone for help. templater.err holds errors, one error object per line. And templater.out is the live view. It carries color encoding, and our docs recommend it if you have an application that can examine a text buffer. On OSX the tail -f command pointed at templater.out shows what Templater is logging as it happens. The color codes are the reason the plain log exists. Our logging page says the color encoding is removed inside templater.log, and that this is the version to share.
The log_location note has one rule worth repeating: the value is a path to a directory, and our key table says not to use a path to a file. If the value is empty, the key table lists the default as empty, and the Templater panel documentation says that when the location is left empty in the Preferences dialog, Templater writes to the logged-in user’s documents folder. That is /Users/username/Documents on macOS and C:\Users\username\Documents on Windows. We suggest you set the key on purpose for any run you do not watch, because a log you cannot find is a log you cannot read.
The launcher scripts help you here too. The PowerShell and Bash launchers report the last logged message and the last reported error after Templater and After Effects finish their tasks. So the end of a run on the command line already shows you the final line of templater.log and the final error object, if there was one. For a short run, that can be all you need. For a long run, the last error is only the last. It tells you nothing about the five that came before it, which is why you open the file.
A word on the panel side, because the same files exist there. Inside After Effects, the Templater panel has a Reset Log button that creates two fresh files named templater.out and templater.log in the log directory, and our docs carry a warning you should treat seriously: if log files already exist, Reset Log erases all of their contents. Show Log opens a window showing the templater.out file. The docs also say that as of Templater 3.3, Templater logs all activity whether or not a project is open, and that a button beside the log location field opens the folder in Finder or Explorer. None of that is a command line feature, but it explains why a panel user and a CLI user see the same file names.
If a log is missing, our troubleshooting table gives two causes for the panel case. You may be searching a different directory than the one tied to the open project, or your user account may lack permission to create files in the folder that holds the project. The fix for the second is to try creating a text file there yourself. If you cannot, change the permissions on the directory. For a command line run, the same instinct applies, so check that the account running the launcher can write to the folder named in log_location.
Reading one error object, line by line
The easiest way to learn the structure is to read the example our documentation prints. It is the object Templater writes to templater.err when After Effects tries to import a footage file that is corrupt or not supported. It lands as a single line in the file, and we have spread it across lines here so you can read it.
{
code : 1001
, desc : "Error swapping footage source"
, ae : "Error: After Effects error: the file format module could not parse the file."
, details : "AE encountered an footage import issue with file B:\Dataclay\Sources\[TEMPLATER DOWNLOADS]\11137842_1428056637497122_561536778_n.jpg. Try manually importing this file into AE to learn more."
, reported : "2020-3-2 @ 14:50:46"
}
There are five properties, and each one answers a different question.
code is a number. Our docs call it a numerical identifier for the reported error, and it is the only field that the options file can act on. Everything else in the object is for a human.
desc is a short description tied to the code. In the example it reads “Error swapping footage source,” and that wording matches the entry for code 1001 in the error code table. Because desc is attached to the code, two errors with the same code show the same desc. That makes it a quick way to confirm you are looking at the kind of error you think you are.
ae is the message of the error thrown by After Effects, if there is one. The docs’ phrase “if any” suggests the field can be empty, and our reading is that an empty field means there was no After Effects message to pass along. In the example, After Effects itself says the file format module could not parse the file. When ae has text, you are reading After Effects speaking.
details is additional information for the specific error, and our docs say it also offers suggestions to troubleshoot the issue. In the example it names the exact file path, and it ends with a direct instruction: try manually importing this file into After Effects to learn more. That is the field that helps a person most, because it points at the actual file or setting. Notice that the path in the example sits inside a folder named TEMPLATER DOWNLOADS. Our root key table explains that footage sources not local to the machine get downloaded to a subfolder with that name inside the source footage path. So this sample points at a downloaded copy, and the folder name tells you the file came from a remote reference.
reported is a time stamp with the date and time the error was reported. For a batch that ran across hours, this field lets you line an error up against the lines in templater.log around the same moment. The two files are meant to be read together, with the .err file telling you what and the .log file telling you what was happening around it.
Here is the habit that follows from this structure. When a run misbehaves, do not read the console first. Open templater.err, find the last object, and read code, then details, then ae. Code tells you the category, details tells you the instance, and ae tells you whether After Effects or Templater raised it. Then open templater.log and search around the reported time to see which row or step was in progress. If the run was hung and produced no error at all, our logging page gives a different rule: take note of the last log message, because that is where it stopped.
The error codes, grouped by what they point at
Our documentation lists twelve codes. Reading them in numeric order is not very helpful, so we have grouped them by the area each one points at. The descriptions below are the ones in the docs, not ours.
Startup and configuration. Code 1 is an error starting the Templater application. Code 2 is an error initializing the Templater CLI. Code 2001 is a command line execution error, and code 2002 is a CLI configuration file error. From their descriptions, these four point at starting up, at the command line, or at the options file. If you see one of them, a reasonable place to look first is the options file and the launch line, since those are the two things you give Templater at the start.
Footage. Code 1001 is an error swapping a footage source, the one in our example. Code 1002 is an error downloading a remote footage source. Code 1003 is that Templater could not find the footage file in the network. These three belong to the footage path, and these are the codes where details may hand you a specific file name to check.
Data. Code 3001 is an error conforming row data from a spreadsheet or TSV file. That is the data source failing to turn into something Templater can use for a row.
Google access. Code 4001 is a Google Open Authentication error, and code 4002 is a Google Drive retrieval error. Code 6001 is an HTTP request error, which sits nearby in spirit because it is also about reaching something over the network.
Layout. Code 5001 is a Templater layout engine error.
Be careful with what this table is and is not. It tells you what each code stands for. It does not say how serious each one is, and it does not say which are safe to ignore. Our pages state no ranking, so any ranking you build is your own judgment. We will give you a way to make that judgment in the next section, but we will mark it as ours.
Stopping a batch on the first matching code
By default, you read the error after the fact. The quit_on_errors key moves the decision earlier. Our key table describes it as an array that enumerates Templater’s error codes, and says that if Templater encounters any error code found in the array, it will force quit the task and After Effects. The troubleshooting page puts the same idea in a sentence about the code property: you can use the error code in the quit_on_errors array to force quit After Effects on the first occurrence of that error.
So the mechanism is plain. You list the codes that should end the run. When one of them is reported, Templater stops the task and quits After Effects at that point, not after the batch. The key’s type is array and its default is empty, so a run with no entry never halts on its own because of an error code. A sketch of the line, using the codes from the table:
"quit_on_errors": [2002, 4001]
That sketch is an illustration, not a recommendation to copy. Which codes belong in it is a question about your batch, and our docs do not answer it. Here is how we would think about it, and this is general practice and not something our pages state.
Ask of each code whether the next row will hit the same wall. A configuration file error, code 2002, describes a problem with the setup, and nothing about the second row will be different from the first. A Google authorization error, code 4001, is the same kind of problem, because the access that failed on one row is the access every later row needs. Letting a batch run to the end in those cases only produces a long file of identical errors and burns time on a machine that cannot succeed. Halting on the first one is the cheaper outcome.
A footage error, code 1001, is the opposite kind of case. In our example, one image could not be parsed. That describes one file. The other rows may be fine. If you put 1001 in quit_on_errors, a single bad image in row 140 ends the run, and you lose the rows behind it. If you leave it out, the batch continues, and the error object waits in templater.err for you to review. Neither choice is wrong. The choice depends on whether a partly finished batch is acceptable to you.
There is a limit you should hold in mind. The docs say the task and After Effects are force quit. They do not say what happens to a render already in progress, or to output written earlier in the batch. So do not assume a halted run leaves clean, finished files behind. After any halt, check the output folder before you trust it.
Also note what the docs describe quit_on_errors as doing. It halts. Our pages do not describe a retry, a row skip or a note logged to a place you choose. If you want an action on error, such as updating a status somewhere, that is the job of an event script, which is a separate feature with its own troubleshooting steps.
When the error is in your own script
Our event script troubleshooting page adds a use of the log that has nothing to do with templater.err. When a script you registered does not behave, the log is where you find the command line Templater actually ran.
The steps in the docs run like this. Open templater.log and search for the phrases EVENT SCRIPT ERROR, EXEC SHELL SCRIPT, or the string you used as the first parameter of the log message method in your own ExtendScript. Find the line that begins with “Full command line” and copy only the command Templater reported. Start a fresh command line session, paste it at the prompt and press Enter. If the script behaves as expected there, the next thing to suspect is the environment Templater runs it in. If it fails there too, look at the script. Running it alone takes Templater out of the question.
Two more ideas from that page are worth borrowing. First, make your scripts write their own trail. The docs show a Bash line that appends text to a debug file on the desktop, a Batch line that does the same on Windows, and an ExtendScript call that writes to Templater’s own log under a label you choose. The ExtendScript form is the neat one, because your message lands in templater.log, the same file Templater writes to. Second, check permissions. A script file has to be executable by the user running After Effects, and our docs give chmod u+x on OSX and the Security tab of the file Properties dialog on Windows.
Taken together, this gives you a working routine for an unattended run. Set log_location on purpose. Decide which codes should end the run and put them in quit_on_errors. Let the launcher show you the last message and error at the end. And when a script is involved, trust the “Full command line” line over your memory of what the script was supposed to do.
A last honest limit. Everything here comes from our documentation, and the docs print one sample error object and one table of codes. They do not catalog every possible value of details or ae, and they do not promise that each code comes with a particular fix. When you hit an error the table does not explain, the log file is what to send to support, and our Templater page points to where to ask. For the Bot side, our guide to monitoring a Bot queue and the page on faults by stage extend this thinking, and our canary row guide shows how to meet a fault on a small run before a large one.
The bottom line: templater.err gives you a number and a sentence for each failure, and quit_on_errors lets that number end the run. Stop on codes that mean every remaining row will fail the same way. Let the batch continue past codes that describe one bad file, and read the error file when it is over.
We went through the files, the object and the halting key. These are the questions we would want answered before relying on them.
Frequently Asked Questions
Where do templater.log, templater.err and templater.out get written?
They are written to the directory set by the log_location key in templater-options.json. The key takes a path to a directory and not a path to a file. The Templater panel documentation says that when the location is left empty, Templater writes to the logged-in user’s documents folder. Setting the key on purpose makes an unattended run easier to inspect afterward, because you know where to look.
What is the difference between templater.log and templater.out?
templater.out carries color encoding and suits an application that can examine a text buffer, for example tail -f on OSX to watch Templater work in real time. templater.log has the color encoding removed, so it opens cleanly in a standard text editor and is the file to share with someone helping you. Both are created in the log directory. Errors go to a third file, templater.err.
What does each field in an error object mean?
code is a numerical identifier, desc is a short description of that code, ae is the message of the error thrown by After Effects if there is one, details gives information about the specific error with troubleshooting suggestions, and reported is a time stamp of the date and time. Only the code can be acted on by the options file, through quit_on_errors. The other four fields are for you to read.
How do I stop a batch the first time a certain error happens?
Add the error code to the quit_on_errors array in templater-options.json. If Templater encounters any code in that array, our documentation says it force quits the task and After Effects. The array is empty by default, so without an entry a run does not halt on an error code. Our pages do not say what happens to a render in progress at that moment, so check your output folder after a halt.
Which error codes should I put in quit_on_errors?
Our documentation lists the codes and their descriptions but does not rank them or recommend any. As general practice, consider halting on codes that describe a setup problem every later row will share, such as a configuration file error or an authorization error, and leaving out codes that describe a single bad file. A halt on a one file error would end the run and skip the rows behind it.
Why does the launcher show only one error when several happened?
The PowerShell and Bash launchers report the last logged message and the last reported error after Templater and After Effects finish. Earlier errors are still in templater.err, one object per line. Open the file to read all of them, and use the reported time stamp on each to line it up with the surrounding lines in templater.log.
How do I find out why my own event script is not running?
Search templater.log for EVENT SCRIPT ERROR or EXEC SHELL SCRIPT, find the line starting “Full command line”, copy that command and paste it into a new command line session. If it runs correctly there, look at the environment Templater runs it in. Also confirm the script is executable by the user running After Effects, which on OSX can be done with chmod u+x.
