Helper Gotchas and Failures

A template that renders nothing is not the same problem as a build that stops, and Leed’s helpers do both. Roughly a dozen helpers reach into an object without checking it first, so a wrong uuid takes the whole build down with a TypeError. Twice that many swallow the same mistake and return an empty string. This page sorts every helper by how it fails, so you can start from the symptom rather than from the helper name.

The mechanics behind all of this — how helpers are registered, why the last argument is always the Handlebars options object, and what SafeString means — are established once in How Helpers Work. This page assumes them.

Failures that stop the build

These helpers dereference something they never checked. When the value is missing you get a TypeError, Eleventy aborts, and leed site build exits non-zero — the page never renders and neither does the rest of the site.

The three helpers that validate their arguments deliberately throw a TypeError whose message is the usage line, which makes them the easiest of the set to diagnose:

usage: {{#date 'iso'|'rfc3339'|'rfc822'|'default' [context]}}{{ e.g. publishedAt }}{{/date}}
usage: {{ latestDate collectionId ['publishedAt','modifiedAt'] }}
field name must be a string

If you see one of those strings in your build output, the fix is always in the call, never in the data.

Two failures that happen before any template renders

Two of Leed’s plugins validate their configuration when Eleventy loads them, not when a template calls them. If the build environment has no domain, the plugin throws while the config is still being assembled:

domain or pagesDomain not set
domain not set

The first comes from the URL helper plugin, the second from the media helper plugin. Tell them apart from a template error by what is missing from the output: no file name, no line number, and no partially-built site, because nothing has rendered yet. This is a build-environment problem — the deployment was started without the site’s domain configuration — and no change to a template will fix it.

Failures that render nothing

This is where the time goes. A helper that returns "" leaves a hole in the page that looks identical to a template that was never written, and most of these say nothing at all unless you ask the build to talk.

collection deserves its own sentence, because its failure is invisible even at the highest log level. A misspelled name returns undefined, and {{#each undefined}} renders nothing without complaint — indistinguishable from a collection that legitimately has no members. If a list is empty and you cannot tell which, print the name you are asking for and compare it against the collection table on Collection, Lookup and Series Helpers.

Run leed site build with those two faults in a layout and the output carries one loud line and one silence:

$ leed site build
  leed:media:error Too few parameters. {url, 'variant name'} are required.
  leed:build:info  rendered 128 pages in 4.2s

The {{ Image src }} call logs leed:media:error and names exactly what it wanted. The {{#each (collection "typo") }} block logs nothing at all — the page simply renders without that section, which is why a missing list is worth grepping the build output for rather than staring at the template.

Every line Leed logs is namespaced leed:<plugin>:<level>, and the plugin half is not always the name you would guess — the documentation-navigation helpers log under menu:navigation, and a dozen small utilities log under uncategorized. Use this table to point --noise at the right channel:

Output that appears as escaped HTML

The symptom is unmistakable: you view source on the built page and find <a href= where a link should be, or a visible <span class="pagination-active"> sitting in the middle of your text. Handlebars escaped the helper’s return value because the helper returned a plain string rather than a SafeString.

Seven helpers return raw markup that Handlebars will escape. Call them with triple braces:

Ten more return a SafeString, so double braces are correct and triple braces buy you nothing:

That last point generalizes. Escaping is correct inside an HTML attribute — = decodes back to = when the browser parses the tag, which is why Leed’s own {{ buildUrl videoSrc "autoplay=true" }} inside a src attribute is fine with double braces. It is only wrong when the output is not HTML at all.

Failures caused by the wrong context

Most helpers read something off this or off the Handlebars options object. Move the same call into a partial, a paginated list item or a feed template and the thing it reads may no longer be there.

Around eight helpers never read this directly. They call an internal unwrapper that walks four levels and takes the first one that looks like page data:

1. options.data.root.list.data — a paginated list item
2. options.data.root — the root page context
3. options.data — the Handlebars data frame
4. the value itself

This is the reason the same helper works on a single page and inside a paginated list item without you passing anything. It is also the reason a helper can work in one place and fail in the other: on a paginated list page step 1 wins, so a helper reads the item’s data, not the list page’s. FeatureImage, FeatureVideo and readingTime compensate by trying both the options object and this before giving up.

date does not compensate, which is why it takes an optional context argument. On a single page, this is the page and no second argument is needed:

{{#date "MMMM D, YYYY"}}{{ publishedAt }}{{/date}}

On a list page, pass the item explicitly so timezone and dateFormat resolve against the item rather than the list:

{{#date "MMMM D, YYYY" this}}{{ publishedAt }}{{/date}}

Arguments in the wrong slot

Handlebars appends the options object as the last argument of every helper call, always. A helper declared with three parameters and called with two therefore receives the options object in its second parameter — and does not receive an options object at all.

Only eight helpers detect this and shift the arguments back into place. On those, omitting the optional middle argument is supported and safe:

pageType · user · label · Authors · Labels · filterObject · sorted · date

Everywhere else, the options object simply becomes your argument. Three shapes of damage follow, in increasing order of nastiness:

The helper treats it as a truthy value. {{ url }} with no argument puts the options object in type; the helper tests type === "relative", which is false, and you get an absolute URL. This one is documented behavior and is why {{ url }} and {{ url "relative" }} are the two supported calls.

The helper loses its options object and cannot function. {{#PaginationLinks}} with no argument does not behave like {{#PaginationLinks true}}. The options object lands in reverse, the real options parameter is undefined, and the helper — which reads the pagination context off that object — logs Pagination links only works inside a pagination context. First parameter must be {reverse:boolean}. and renders nothing at all.

The helper interpolates it into your output. imageUrl guards with if (!variant), and the options object is perfectly truthy, so the guard never fires. The helper then runs url.replace("original", options), JavaScript stringifies the object, and the variant segment of the emitted URL becomes the literal text [object Object]. The image 404s and nothing is logged.

{{ imageUrl image }}

That is the broken call. This is the correct one:

{{ imageUrl image "profile" }}

previousPageNav and nextPageNav fail the same way: with no label argument the options object lands in the label slot and is interpolated straight into the markup, so the sub-label of the link reads [object Object]. Leed’s own partial routes an unset label through default rather than leaving the argument off, and Documentation Navigation Helpers shows the pattern.

If a built page carries [object Object] anywhere, an omitted argument is almost always the cause. The full account of why the options object is always last lives in How Helpers Work.

Name collisions and missing helpers

Leed’s 64 helpers are registered onto the Handlebars instance after the handlebars-helpers library, so where the two libraries share a name, Leed’s wins. There is exactly one such collision, and it matters:

The library’s whole string category is deliberately not installed — its reverse helper collides with the array category’s. Thirty-six helper names you might reasonably expect are therefore unavailable, and calling one is a build-stopping error, not a quiet blank:

Missing helper: "truncate"

Handlebars raises that whenever an unregistered name is called with an argument ({{ truncate title 40 }}) or as a block ({{#truncate …}}). The one shape that fails quietly is a bare {{ truncate }} with no arguments, which Handlebars treats as a property lookup on the context and resolves to an empty string.

One further name to strike from older notes: addAnchorReason does not exist. It was removed and replaced by a build-time data-reason convention on recommendation links; there is nothing to call.

A symptom index

Start here when you know what you are seeing but not what caused it.

When the message you are chasing came from the CLI or the CMS rather than from a helper, Common Error Messages is the wider list, and every helper’s own parameters and defaults are on its group page — reachable by name from the Helper Index.