Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Handlebars throws Missing helper when a template calls a name it does not know

ErrorError: Missing helper: "formatDate"

Short answer

Handlebars throws Missing helper when a mustache has arguments and its name is neither a registered helper nor a context property. Either the helper was never registered with Handlebars or express-handlebars, or you wrote a property path with a space where a dot belongs. Register the helper or fix the expression.

  • Applies to Handlebars 4.7, express-handlebars 8, Node.js 22, Express 5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    The quoted name in the message is what Handlebars could not resolve. Search your templates for that exact name.

    grep -rn "formatDate" views/
  2. 2Match what you see, then jump to its fix

    1. 1Missing helper: "<name>" for a function you meant to call, like formatDateThe helper was never registeredFix
    2. 2Missing helper: "user" for a template such as {{user name}}A property path was written with a space, so it is read as a helper callFix
    3. 3Templates come from content authors and may use names that do not existA missing-helper handler is needed for names you cannot know in advanceFix

What does the error look like?

  • Error: Missing helper: "formatDate"
  • Error: Missing helper: "name"
  • Error thrown from res.render('home')

Cause 1 of 3

The helper was never registered

1Check

A helper called with parameters must exist at render time. With express-handlebars, helpers come from the global registerHelper, the helpers option on create() or engine(), or the render call.

grep -rn "registerHelper\|helpers:" src/ app.js

2Fix

Register it on the instance that renders your views.

import { create } from 'express-handlebars';
const hbs = create({
  helpers: {
    formatDate(d) { return new Date(d).toLocaleDateString('en-GB'); },
  },
});
app.engine('handlebars', hbs.engine);
app.set('view engine', 'handlebars');

3Verify

Render the page again. The helper output replaces the error.

curl -s http://localhost:3000/ | grep -i "error" || echo ok

Confirmed by github.com

Did this fix it?

Cause 2 of 3

A property path was written with a space, so it is read as a helper call

1Check

A helper call is a name followed by space-separated parameters. {{user name}} calls a helper called user with the parameter name, while a property path uses a dot.

grep -rn "{{[a-zA-Z]* [a-zA-Z]*}}" views/

2Fix

Use a dot for property access. If a helper and a property share a name, the helper wins, and ./ or this. selects the property.

{{user.name}}
{{this.name}}

3Verify

Reload the page and confirm the value renders.

curl -s http://localhost:3000/profile

Confirmed by handlebarsjs.com

Did this fix it?

Cause 3 of 3

A missing-helper handler is needed for names you cannot know in advance

1Check

By default, a mustache with no parameters is ignored, while one with a parameter throws. Handlebars lets you register a helper named helperMissing to decide what happens.

grep -rn "helperMissing" src/

2Fix

Register helperMissing that returns an empty string or a safe marker. The name being called is in options.name.

Handlebars.registerHelper('helperMissing', function (...args) {
  const options = args[args.length - 1];
  console.warn('Unknown helper', options.name);
  return '';
});

3Verify

Render a template with an unknown helper. It logs a warning and the page still loads.

curl -s http://localhost:3000/ | head -n 20

Confirmed by handlebarsjs.com

Did this fix it?

How do I stop it coming back?

  • Keep helpers in one module that is imported before the first render.
  • Use strict dotted paths for data and reserve spaces for real helper calls.
  • Render each template in a test so a missing name fails in CI, not in production.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.