A field type mismatch in Templater is a value that reaches a layer or property in a form it cannot use. In Templater 3.5 and later, a wrongly typed essential property is skipped and an error is written to the log. A font that cannot draw the language, or a footage path that points at nothing, behaves differently. Templater handles each of these in its own way. Some are skipped with a note in the log. Some change the output in a way that looks like a bug. A few stop the batch.
Whether the data comes from a Google Sheet, a tab-separated file, a JSON file, a URL feed or a Que campaign, many of the same ideas apply, because Templater maps rows and JSON objects to render jobs, and columns and JSON keys to dynamic elements. Some rules are specific to one source type, as below. This article collects what our documentation says about the mismatches you are most likely to meet, which ones fail loudly and which fail quietly, and a short routine for catching them before a large batch. Where the documentation does not say what happens, we say that too. For the sheet side in depth, see our complete reference to using Templater with Google Sheets.
Data is read as text, and the target property expects a type
Start with how Templater thinks about data. A data source is a table. Each row of a spreadsheet, or each object in a JSON array, is one render job. Each column, or each property key, is one dynamic element in the template. A spreadsheet cell holds text, URLs, image file paths or hex color values. For promoted properties, the type comes from what the receiving property expects.
Our expression documentation makes the same point from the other direction. It states that all Templater data are interpreted as strings. If you reference a dynamic text layer’s Source Text, or a data parameter from Templater’s JSON footage, in expression code, the value is a string. The documentation recommends casting it to the type your code needs. It names parseInt() for an integer, parseFloat() for a float, parseNumber() for either, and eval() for an object or array. For JSON footage, it adds that all property values in the generated templater-data.json file are strings because of how After Effects handles changes in imported JSON footage. The documentation recommends casting the string to the type your code needs.
The JSON side deserves one note. A JSON source can nest objects, for example a group of essential properties. Our documentation does not describe how other JSON value types are handled, and we will not guess. What it does say is that property keys in a JSON object are equivalent to column names in a spreadsheet, and the rest of this article follows the places where it describes behavior.
Most mismatches fall into three groups. There are properties promoted to the Essential Properties panel, which have declared types. There are text style values, which are small JSON strings inside a cell. And there are footage references, where the “type” is a file that must exist. We take them in that order.
Where a mismatch is loud and where it is quiet
Essential properties have the clearest rules. Templater 3.5 and later can use data to change values for properties promoted to the Essential Properties panel. It does this on the pre-comp layer that is an instance of the primary composition, not on the primary composition itself. Our documentation gives a table of the types to use in the data source. A color is entered as a hex code such as #FFFFFF, while the panel itself shows it as an RGB array like [51,255,172]. A numeric property takes a numeric value such as 67. A boolean takes true to turn the property on and false to turn it off. A grouped property is entered as an object named for the group, with the property names inside it.
The consequence of a wrong type is written down. If the type of data in your data source does not match what is expected, Templater skips that property key and writes an error to its log file. That is the quiet kind of failure, because Templater writes the error to its log file. If the mismatched property is a media asset, Templater instead respects the preference you have set for missing or faulty footage, which we cover below.
Three more rules from that page matter here. The key name must be an exact match for the property name in the Essential Properties panel, and when the property sits in a group, the group name must be part of the key. A key that is missing, or whose value is null or undefined, makes Templater use the default value, because Templater reloads all the default values from the primary comp before each job and changes only the pairs present in that job’s data. And if the same property appears both in a combined assembly@egp column or object and in its own assembly@[property name] column, the individual property wins.
Here is a short example. Suppose a pre-comp layer named assembly exposes a color called Title Fill Color, a number called Badge Size and a boolean called Show Badge. A row that holds #1A8F5C, 67 and true maps cleanly. A row that holds a color word, a size with a unit written into the cell, and the word “yes” is a different story. Our documentation lists two forms for color values in different places, a hex code in the type table and an RGB array in an example, and it does not list color names, units or yes and no as accepted. If you rely on anything outside the documented forms, test it in a preview first. When Templater rejects a value, the log is where it says so.
If your spreadsheet supports JSON inside a cell, you can put several properties in one column named assembly@egp. That makes the cell itself a small JSON document. We would keep these cells short and test each row type in a preview.
Dynamic text styling uses JSON strings in a cell. The @style feature, available from Templater 3.4, reads a column named after the text layer with @style added, such as title@style. The cell holds values like {"font-face":"ArialMT","direction":"LTR"}. Our documentation spells out what happens when the value does not fit. If you name a font that is installed, Templater imports the text and uses that font. If you name a font that is not installed, Windows uses the system default font and macOS produces unexpected results. If the font is installed but does not support the language of the text, Templater does not import the text and no text appears in the comp for that row. If you leave the style cell blank, the text renders with the defaults in Templater Preferences. An empty direction becomes left-to-right, and an empty justification is matched to the direction. Some direction and justification pairs are edge cases that After Effects does not support, and in most cases Templater matches justification to direction.
The font case is the one to remember. A font that cannot draw the language means Templater does not import the text and no text appears for that row. Our documentation does not say whether this is logged. If you localize, run one row per language through a preview and look at it. The font-face value is the PostScript name of the font, which you can search for in the Text Settings tab of Templater Preferences.
Footage references are a type check on a file. A footage cell is a path or URL, and it either resolves to a file After Effects can import or it does not. You decide what happens in Templater Preferences, under Footage. The option “Consider empty cells or null values as faulty” decides whether empty cells count as a problem. If it is off, an empty cell or null value makes Templater hold over the item from the previously previewed row, so the footage layer is left untouched. That can be surprising, because the footage layer stays as it was for the previous row. For references that cannot be found or imported, the choices are: ask what to do, let you find the asset, skip the row, use a branded placeholder, or cancel the process. Asking halts processing and shows a dialog. We would avoid that on an unattended machine. Our documentation recommends the branded placeholder, because it keeps batch processing running smoothly, and since Templater 2.9.5 it is the default. References are also case-sensitive, so a file name that differs only by capital letters is a mismatch.
Mismatches that come from the file, not the field
Some of the most common type problems are not about a value at all. They come from how the source was made.
Header names in Google Sheets. Templater does not currently support column headers that begin with a numeral, contain spaces or contain the _ character. Our troubleshooting page also lists the dollar symbol. A header like that will not map to a layer, so the layer will not update when you preview. The fix is to rename the header, rename the layer to match, and preview again.
Tab-delimited files exported from Excel or Numbers. Templater has a preference for tab-delimited files exported from those two programs. If you exported from one of them and the box is not checked, or you did not and the box is checked, unintended characters appear in dynamic text layers. TSV and JSON text files must also be UTF-8 encoded so that international characters read correctly.
Line breaks. If multi-line text does not display correctly, there are two causes in our documentation. The text layer may have been created as a single-line text box by clicking, instead of a multi-line box made by click-and-dragging with the Text tool. Or the new line character in the data may not be interpreted correctly by After Effects, in which case you should use your spreadsheet application’s native method for multi-line entries.
Reserved names. The names id, target, output, aep, render-status, bot, module and render-settings are reserved, they are case-sensitive, and using one as a dynamic layer name can cause an error. The values in module and render-settings columns are case-sensitive too. The render-status column should hold only reserved terms or stay empty. Our article on what happens when a data column name matches a reserved Templater name goes deeper.
Row conforming errors. When you run Templater from the command line, error code 3001 is described as an error conforming row data from a spreadsheet or TSV file. The error object also carries a short description and a timestamp.
How to catch them before a batch
We do not have a feature in our documentation that validates types across a whole data source. What we do have is a set of tools that expose them one row at a time. Here is the routine we suggest, built from those tools.
First, turn on the log. In Templater Preferences, under Advanced, choose a directory for the log. Then use Reset Log to create fresh templater.out and templater.log files. Remember that Reset Log erases existing contents. Run your preview or a small batch, and read the log for skipped keys.
Second, preview deliberately. The preview menu has to be set to something other than current state, such as next row, or the composition will not move to another row. Manual preview re-reads your data source each time and does not use caching. Cycle mode reads the data source only once before it starts, so newly added data will not show up in the middle of a cycle. Choose rows that cover each kind of value your data holds: the shortest text, the longest text, every language, an empty footage cell, a row with a missing key.
Third, use spot checks on a larger range. Spot checks are still images or short clips of selected frames from data-merged compositions, and they work in Templater Pro and Bot. If you pay per output through the Que Meter, remember each spot check uses a credit.
Fourth, decide your footage policy before you start. Use the branded placeholder and a visible placeholder image, so a bad reference is obvious in the video rather than silent. This is our suggestion, built on the documented options.
Our article on handling dirty or incomplete data without producing broken output videos covers the data-quality side. If your sources include a feed, see the five data sources you can use with Templater.
The bottom line is that several type problems fail quietly. Essential properties skip the key and log it. Fonts that cannot draw a language leave a gap. Empty footage cells can show the previous row. Read the log, preview a spread of rows, pick a footage policy on purpose, and the quiet failures become visible before your batch does the work. The Templater page shows the editions, and the Learn section collects our other guides.
These are the questions we hear most when a value lands in the wrong form.
Frequently Asked Questions
Does Templater convert text to numbers, colors or booleans for me?
For essential properties, you enter the type the property expects: a numeric value, a hex code for a color, or true and false for a boolean. If the type does not match, Templater skips that key and writes an error to its log. In expressions, all Templater data are strings, so you cast them with functions such as parseInt, parseFloat and eval before doing arithmetic.
What happens when an essential property value is the wrong type?
Templater skips that property key and writes an error to its log file. Templater reloads the primary composition’s default values before each job and changes only the pairs it applies. If the mismatched property is a media asset, Templater follows your preference for faulty or missing footage instead. Read the log after a test run so a skipped key does not reach production.
Why does one row show the picture from the row before it?
Probably an empty or null footage cell. If the preference to consider empty cells or null values as faulty is off, Templater holds over the item from the previously previewed row and leaves the footage layer untouched. Turn the preference on and choose how faulty references are handled, or fill the cell.
Why does my translated text not appear at all?
The font named in your style column may be installed but unable to support that language. In that case Templater does not import the text, and no text appears for that row. Choose a font that supports the language, and preview one row per language before you render.
Do Google Sheets, JSON and URL feed sources follow different rules?
Many of the same ideas apply, since rows and JSON objects are both render jobs and columns and property keys are both dynamic elements. Some rules are specific to a source type: are in the source format: Google Sheets headers cannot begin with a numeral or contain spaces, the _ character or a dollar sign, tab-delimited files need the right Excel or Numbers setting, and text files must be UTF-8.
How do I find out which rows have a problem before a large batch?
Turn on the log, preview a spread of rows that includes your shortest text, longest text, each language and any empty footage cells, and run spot checks over a range. With the Bot, a row that cannot be processed gets an error status such as ERR::MEDIA or ERR::AFXHOST. Our documentation does not describe a feature that validates every row at once.
